<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="version" content="0.17"/>
  <meta name="subject" content="package manager"/>
  <meta name="title" content="Package Manager"/>
  <meta name="copyright" content="2014-2024 the build2 authors"/>

  <title>The build2 Package Manager</title>

  <style type="text/css">
/* file      : common.css
 * license   : MIT; see accompanying LICENSE file
 */

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard paragraph. */

p, pre {margin: 1em 0 1em 0;}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}
@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

/* file      : pre-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css. */

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* file      : code-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css if changing anything here. */

code
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .2em .32em .18em .32em;
}

/* file      : toc.css
 * license   : MIT; see accompanying LICENSE file
 */

table.toc
{
  border-style      : none;
  border-collapse   : separate;
  border-spacing    : 0;

  margin            : 0.2em 0 0.2em 0;
  padding           : 0 0 0 0;
}

table.toc tr
{
  padding           : 0 0 0 0;
  margin            : 0 0 0 0;
}

table.toc * td, table.toc * th {
  border-style      : none;
  margin            : 0 0 0 0;
  vertical-align    : top;
}

table.toc * th
{
  font-weight       : normal;
  padding           : 0 0.8em 0 0;
  text-align        : left;
  white-space       : nowrap;
}

table.toc * table.toc th
{
  padding-left      : 1em;
}

table.toc * td
{
  padding           : 0 0 0 0;
  text-align        : left;
}

table.toc * td.preface
{
  padding-left      : 1.35em;
}

/* file      : intro.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Bases:
 *
 * common.css
 * pre-box.css
 * code-box.css
 *
 */

#content
{
  max-width: 43.6em;
  padding-left: 3em; /* Reserve for headings. */
}

h1
{
  font-weight: normal;
  font-size: 2em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -1.4em;
}

h1.preface
{
  margin-left: -.56em;
}

h2
{
  font-weight: normal;
  font-size: 1.556em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.8em;
}

h3
{
  font-weight: normal;
  font-size: 1.3em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.2em;
}

/* Title page */

#titlepage {
  margin: 0 0 4em 0;
  border-bottom: 1px solid black;
}

#titlepage .title {
  font-weight: normal;
  font-size: 2.333em;
  line-height: 1.4em;
  letter-spacing: 0;
  text-align: center;
  margin: 2em 0 2em 0;
}

#titlepage p {
  font-size: 0.889em;
  line-height: 1.4em;
  margin: 2em 0 .6em 0;
}

  </style>

</head>
<body>
<div id="content">

  <div class="noprint"> <!-- Exclude from html2ps. -->

  <div id="titlepage">
    <div class="title">The <code>build2</code> Package Manager</div>

    <p id="revision">Revision <code>0.17</code>, June 2024<br/>
    This revision of the document describes the <a href="https://build2.org"><code>build2</code></a>
    package manager <code>0.17.X</code> series and is available in the
    following formats:
    <a href="build2-package-manager-manual.xhtml">XHTML</a>,
    <a href="build2-package-manager-manual-a4.pdf">PDF/A4</a>,
    <a href="build2-package-manager-manual-letter.pdf">PDF/Letter</a>,
    <a href="build2-package-manager-manual-a4.ps">PostScript/A4</a>, and
    <a href="build2-package-manager-manual-letter.ps">PostScript/Letter</a>.</p>

    <p>Copyright &#169; 2014-2024 the build2 authors.<br/>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the MIT License.</p>
  </div>

  <h1>Table of Contents</h1>

  <table class="toc">
    <tr><td class="preface" colspan="2"><a
href="#preface">Preface</a></td></tr>
    <tr><th>1</th><td><a href="#package-name">Package Name</a></td></tr>
    <tr><th>2</th><td><a href="#package-version">Package Version</a></td></tr>
    <tr><th>3</th><td><a href="#package-version-constraint">Package Version
Constraint</a></td></tr>
    <tr><th>4</th><td><a href="#package-skeleton">Package Build System
Skeleton</a></td></tr>
    <tr><th>5</th><td><a href="#dep-config-negotiation">Dependency
Configuration Negotiation</a>
      <table class="toc">
        <tr><th>5.1</th><td><a href="#dep-config-prefer-x-accept-xy">Prefer X
but Accept X or Y</a></td></tr>
        <tr><th>5.2</th><td><a href="#dep-config-use-if-enabled">Use If
Enabled</a></td></tr>
        <tr><th>5.3</th><td><a href="#dep-config-disable-default">Disable If
Enabled by Default</a></td></tr>
      </table>
    </td></tr>
    <tr><th>6</th><td><a href="#manifests">Manifests</a>
      <table class="toc">
        <tr><th>6.1</th><td><a href="#manifest-format">Manifest
Format</a></td></tr>
        <tr><th>6.2</th><td><a href="#manifest-package">Package Manifest</a>
          <table class="toc">
            <tr><th>6.2.1</th><td><a
href="#manifest-package-name"><code>name</code></a></td></tr>
            <tr><th>6.2.2</th><td><a
href="#manifest-package-version"><code>version</code></a></td></tr>
            <tr><th>6.2.3</th><td><a
href="#manifest-package-type-language"><code>type</code>,
<code>language</code></a></td></tr>
            <tr><th>6.2.4</th><td><a
href="#manifest-package-project"><code>project</code></a></td></tr>
            <tr><th>6.2.5</th><td><a
href="#manifest-package-"><code>priority</code></a></td></tr>
            <tr><th>6.2.6</th><td><a
href="#manifest-package-summary"><code>summary</code></a></td></tr>
            <tr><th>6.2.7</th><td><a
href="#manifest-package-license"><code>license</code></a></td></tr>
            <tr><th>6.2.8</th><td><a
href="#manifest-package-topics"><code>topics</code></a></td></tr>
            <tr><th>6.2.9</th><td><a
href="#manifest-package-keywords"><code>keywords</code></a></td></tr>
            <tr><th>6.2.10</th><td><a
href="#manifest-package-description"><code>description</code>,
<code>package-description</code></a></td></tr>
            <tr><th>6.2.11</th><td><a
href="#manifest-package-changes"><code>changes</code></a></td></tr>
            <tr><th>6.2.12</th><td><a
href="#manifest-package-url"><code>url</code></a></td></tr>
            <tr><th>6.2.13</th><td><a
href="#manifest-package-doc-url"><code>doc-url</code></a></td></tr>
            <tr><th>6.2.14</th><td><a
href="#manifest-package-src-url"><code>src-url</code></a></td></tr>
            <tr><th>6.2.15</th><td><a
href="#manifest-package-package-url"><code>package-url</code></a></td></tr>
            <tr><th>6.2.16</th><td><a
href="#manifest-package-email"><code>email</code></a></td></tr>
            <tr><th>6.2.17</th><td><a
href="#manifest-package-package-email"><code>package-email</code></a></td></tr>
            <tr><th>6.2.18</th><td><a
href="#manifest-package-build-email"><code>build-email</code></a></td></tr>
            <tr><th>6.2.19</th><td><a
href="#manifest-package-warning-email"><code>build-warning-email</code></a></td></tr>
            <tr><th>6.2.20</th><td><a
href="#manifest-package-error-email"><code>build-error-email</code></a></td></tr>
            <tr><th>6.2.21</th><td><a
href="#manifest-package-depends"><code>depends</code></a></td></tr>
            <tr><th>6.2.22</th><td><a
href="#manifest-package-requires"><code>requires</code></a></td></tr>
            <tr><th>6.2.23</th><td><a
href="#manifest-package-tests-examples-benchmarks"><code>tests</code>,
<code>examples</code>, <code>benchmarks</code></a></td></tr>
            <tr><th>6.2.24</th><td><a
href="#manifest-package-builds"><code>builds</code></a></td></tr>
            <tr><th>6.2.25</th><td><a
href="#manifest-package-include-exclude"><code>build-{include,
exclude}</code></a></td></tr>
            <tr><th>6.2.26</th><td><a
href="#manifest-package-build-auxiliary"><code>build-auxiliary</code></a></td></tr>
            <tr><th>6.2.27</th><td><a
href="#manifest-package-build-bot"><code>build-bot</code></a></td></tr>
            <tr><th>6.2.28</th><td><a
href="#manifest-package-build-config"><code>*-build-config</code></a></td></tr>
            <tr><th>6.2.29</th><td><a
href="#manifest-package-build-file"><code>build-file</code></a></td></tr>
            <tr><th>6.2.30</th><td><a
href="#manifest-package-distribution"><code>*-{name, version,
to-downstream-version}</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>6.3</th><td><a href="#manifest-package-list-pkg">Package List
Manifest for <code><b>pkg</b></code> Repositories</a>
          <table class="toc">
            <tr><th>6.3.1</th><td><a
href="#manifest-package-list-pkg-sha256sum"><code>sha256sum</code> (list
manifest)</a></td></tr>
            <tr><th>6.3.2</th><td><a
href="#manifest-package-list-pkg-package-location"><code>location</code>
(package manifest)</a></td></tr>
            <tr><th>6.3.3</th><td><a
href="#manifest-package-list-pkg-package-sha256sum"><code>sha256sum</code>
(package manifest)</a></td></tr>
          </table>
        </td></tr>
        <tr><th>6.4</th><td><a href="#manifest-package-list-dir">Package List
Manifest for <code><b>dir</b></code> Repositories</a>
          <table class="toc">
            <tr><th>6.4.1</th><td><a
href="#manifest-package-list-dir-location"><code>location</code></a></td></tr>
            <tr><th>6.4.2</th><td><a
href="#manifest-package-list-dir-fragment"><code>fragment</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>6.5</th><td><a href="#manifest-repository">Repository
Manifest</a>
          <table class="toc">
            <tr><th>6.5.1</th><td><a
href="#manifest-repository-location"><code>location</code></a></td></tr>
            <tr><th>6.5.2</th><td><a
href="#manifest-repository-type"><code>type</code></a></td></tr>
            <tr><th>6.5.3</th><td><a
href="#manifest-repository-role"><code>role</code></a></td></tr>
            <tr><th>6.5.4</th><td><a
href="#manifest-repository-trust"><code>trust</code></a></td></tr>
            <tr><th>6.5.5</th><td><a
href="#manifest-repository-url"><code>url</code></a></td></tr>
            <tr><th>6.5.6</th><td><a
href="#manifest-repository-email"><code>email</code></a></td></tr>
            <tr><th>6.5.7</th><td><a
href="#manifest-repository-summary"><code>summary</code></a></td></tr>
            <tr><th>6.5.8</th><td><a
href="#manifest-repository-description"><code>description</code></a></td></tr>
            <tr><th>6.5.9</th><td><a
href="#manifest-repository-certificate"><code>certificate</code></a></td></tr>
            <tr><th>6.5.10</th><td><a
href="#manifest-repository-fragment"><code>fragment</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>6.6</th><td><a href="#manifest-repository-list">Repository
List Manifest</a>
          <table class="toc">
            <tr><th>6.6.1</th><td><a
href="#manifest-repository-list-header-min-bpkg-version"><code>min-bpkg-version</code></a></td></tr>
            <tr><th>6.6.2</th><td><a
href="#manifest-repository-list-header-compression"><code>compression</code></a></td></tr>
          </table>
        </td></tr>
        <tr><th>6.7</th><td><a href="#manifest-signature-pkg">Signature
Manifest for <code><b>pkg</b></code> Repositories</a>
          <table class="toc">
            <tr><th>6.7.1</th><td><a
href="#manifest-signature-pkg-sha256sum"><code>sha256sum</code></a></td></tr>
            <tr><th>6.7.2</th><td><a
href="#manifest-signature-pkg-signature"><code>signature</code></a></td></tr>
          </table>
        </td></tr>
      </table>
    </td></tr>
    <tr><th>7</th><td><a href="#bindist-mapping">Binary Distribution Package
Mapping</a>
      <table class="toc">
        <tr><th>7.1</th><td><a href="#bindist-mapping-debian">Debian Package
Mapping</a>
          <table class="toc">
            <tr><th>7.1.1</th><td><a
href="#bindist-mapping-debian-consume">Debian Package Mapping for
Consumption</a></td></tr>
            <tr><th>7.1.2</th><td><a
href="#bindist-mapping-debian-produce">Debian Package Mapping for
Production</a></td></tr>
          </table>
        </td></tr>
        <tr><th>7.2</th><td><a href="#bindist-mapping-fedora">Fedora Package
Mapping</a>
          <table class="toc">
            <tr><th>7.2.1</th><td><a
href="#bindist-mapping-fedora-consume">Fedora Package Mapping for
Consumption</a></td></tr>
            <tr><th>7.2.2</th><td><a
href="#bindist-mapping-fedora-produce">Fedora Package Mapping for
Production</a></td></tr>
          </table>
        </td></tr>
      </table>
    </td></tr>
  </table>

  </div> <!-- noprint -->
  <h1 id="preface" class="preface">Preface</h1>

  <p>This document describes <code>bpkg</code>, the <code>build2</code>
  package dependency manager. For the package manager command line interface
  refer to the <a href="bpkg.xhtml"><code><b>bpkg(1)</b></code></a> man
  pages.</p>

  <h1 id="package-name">1 Package Name</h1>

  <p>The <code>bpkg</code> package name can contain ASCII alphabetic
  characters (<code>[a-zA-Z]</code>), digits (<code>[0-9]</code>), underscores
  (<code>_</code>), plus/minus (<code>+-</code>), and dots/periods
  (<code><code>.</code></code>). The name must be at least two characters long
  with the following additional restrictions:</p>

  <ol>
  <li>It must start with an alphabetic character.</li>

  <li>It must end with an alphabetic, digit, or plus character.</li>

  <li>It must not be any of the following illegal names:

  <pre>build
con prn aux nul
com1 com2 com3 com4 com5 com6 com7 com8 com9
lpt1 lpt2 lpt3 lpt4 lpt5 lpt6 lpt7 lpt8 lpt9</pre></li>
  </ol>

  <p>The use of the plus (<code>+</code>) character in package names is
  discouraged. <span class="note">Pluses are used in URL encoding which makes
  specifying packages that contain pluses in URLs cumbersome.</span></p>

  <p>The use of the dot (<code>.</code>) character in package names is
  discouraged except for distinguishing the implementations of the same
  functionality for different languages. <span class="note">For example,
  <code>libfoo</code> and <code>libfoo.bash</code>.</span></p>

  <p>Package name comparison is case-insensitive but the original case must be
  preserved for display, in file names, etc. <span class="note">The reason for
  case-insensitive comparison is Windows file names.</span></p>

  <p>If the package is a library then it is strongly recommended that you
  start its package name with the <code>lib</code> prefix, for example,
  <code>libfoo</code>. Some package repositories may make this a requirement
  as part of their submission policy.</p>

  <p>If a package (normally a library) supports usage of multiple major
  versions in the same project, then it is recommended to append the major
  version number to the package name starting from version <code>2.0.0</code>,
  for example, <code>libfoo</code> (before <code>2.0.0</code>),
  <code>libfoo2</code> (<code>2.Y.Z</code>), <code>libfoo3</code>
  (<code>3.Y.Z</code>), etc.</p>

  <h1 id="package-version">2 Package Version</h1>

  <p>The <code>bpkg</code> package version format tries to balance the need of
  accommodating existing software versions on one hand and providing a
  reasonably straightforward comparison semantics on another. For some
  background on this problem see <code><b>deb-version(1)</b></code> and the <a
  href="http://semver.org">Semantic Versioning</a> specification.</p>

  <p>Note also that if you are starting a new project that will use the
  <code>build2</code> toolchain, then it is strongly recommended that you use
  the <i>standard versioning</i> scheme which is a more strictly defined
  subset of semantic versioning that allows automation of many version
  management tasks. See <a
  href="../../build2/doc/build2-build-system-manual.xhtml#module-version"><code>version</code>
  Module</a> for details.</p>

  <p>The <code>bpkg</code> package version has the following form:</p>

  <pre>[+&lt;epoch>-]&lt;upstream>[-&lt;prerel>][+&lt;revision>][#&lt;iteration>]</pre>

  <p>The <i>epoch</i> part should be an integer. It can be used to change to a
  new versioning scheme that would be incompatible with the old one. If not
  specified, then <i>epoch</i> defaults to <code>1</code> except for a stub
  version (see below) in which case it defaults to <code>0</code>. The
  explicit zero <i>epoch</i> can be used if the current versioning scheme (for
  example, date-based) is known to be temporary.</p>

  <p>The <i>upstream</i> part is the upstream software version that this
  package is based on. It can only contain alpha-numeric characters and
  <code>.</code>. The <code>.</code> character is used to separate the version
  into <i>components</i>.</p>

  <p>The <i>prerel</i> part is the upstream software pre-release marker, for
  example, alpha, beta, candidate, etc. Its format is the same as for
  <i>upstream</i> except for two special values: the absent <i>prerel</i> (for
  example, <code>1.2.3</code>) signifies the maximum or final release while
  the empty <i>prerel</i> (for example, <code>1.2.3-</code>) signifies the
  minimum or earliest possible release. <span class="note">The minimum release
  is intended to be used for version constraints (for example, <code>libfoo
  &lt; 1.2.3-</code>) rather than actual releases.</span></p>

  <p>The <i>revision</i> part should be an integer. It is used to version
  package releases that are based on the same upstream versions. If not
  specified, then <i>revision</i> defaults to <code>0</code>.</p>

  <p>The <i>iteration</i> part is an integer. It is used internally by
  <code>bpkg</code> to automatically version modifications to the packaging
  information (specifically, to package manifest and lockfile) in <i>external
  packages</i> that have the same upstream version and revision. As a result,
  the <i>iteration</i> cannot not be specified by the user and is only shown
  in the <code>bpkg</code> output (for example, by <code>pkg-status</code>
  command) in order to distinguish between package iterations with otherwise
  identical versions. Note also that <i>iteration</i> is relative to the
  <code>bpkg</code> configuration. Or, in other words, it is an iteration
  number of a package as observed by a specific configuration. As a result,
  two configurations can "see" the same package state as two different
  iterations.</p>

  <div class="note">
  <p>Package iterations are used to support package development during which
  requiring the developer to manually increment the version or revision after
  each modification would be impractical. This mechanism is similar to the
  automatic commit versioning provided by the <i>standard version</i> except
  that it is limited to the packaging information but works for uncommitted
  changes.</p>
  </div>

  <p>Version <code>+0-0-</code> (least possible version) is reserved and
  specifying it explicitly is illegal. <span class="note">Explicitly
  specifying this version does not make much sense since <code>libfoo &lt;
  +0-0-</code> is always false and <code>libfoo > +0-0-</code> is always true.
  In the implementation this value is used as a special empty
  version.</span></p>

  <p>Version <code>0</code> (with a potential revision, for example,
  <code>0+1</code>, <code>0+2</code>) is used to signify a <i>stub
  package</i>. A stub is a package that does not contain source code and can
  only be "obtained" from other sources, for example, a system package
  manager. Note that at some point a stub may be converted into a full-fledged
  package at which point it will be assigned a "real" version. It is assumed
  that this version will always be greater than the stub version.</p>

  <p>When displaying the package version or when using the version to derive
  the file name, the default <i>epoch</i> value as well as zero
  <i>revision</i> and <i>iteration</i> values are omitted (even if they were
  explicitly specified, for instance, in the package manifest). For example,
  <code>+1-1.2.3+0</code> will be used as <code>libfoo-1.2.3</code>.</p>

  <div class="note">
  <p>This versioning scheme and the choice of delimiter characters
  (<code>.-+</code>) is meant to align with semantic versioning.</p>
  </div>

  <p>Some examples of versions:</p>

  <pre>0+1
+0-20180112
1.2.3
1.2.3-a1
1.2.3-b2
1.2.3-rc1
1.2.3-alpha1
1.2.3-alpha.1
1.2.3-beta.1
1.2.3+1
+2-1.2.3
+2-1.2.3-alpha.1+3
+2.2.3#1
1.2.3+1#1
+2-1.2.3+1#2</pre>

  <p>The version sorting order is <i>epoch</i>, <i>upstream</i>,
  <i>prerel</i>, <i>revision</i>, and finally, <i>iteration</i>. The
  <i>upstream</i> and <i>prerel</i> parts are compared from left to right, one
  component at a time, as described next.</p>

  <p>To compare two components, first the component types are determined.  A
  component that only consists of digits is an integer. Otherwise, it is a
  string. If both components are integers, then they are compared as integers.
  Otherwise, they are compared lexicographically and case-insensitively. <span
  class="note">The reason for case-insensitive comparison is Windows file
  names.</span></p>

  <p>A non-existent component is considered 0 if the other component is an
  integer and an empty string if the other component is a string.  For
  example, in <code>1.2</code> vs <code>1.2.0</code>, the third component in
  the first version is 0 and the two versions are therefore equal. As a
  special exception to this rule, an absent <i>prerel</i> part is always
  greater than any non-absent part. <span class="note">And thus making the
  final release always older than any pre-release.</span></p>

  <p>This algorithm gives correct results for most commonly-used versioning
  schemes, for example:</p>

  <pre>1.2.3 &lt; 12.2
1.alpha &lt; 1.beta
20151128 &lt; 20151228
2015.11.28 &lt; 2015.12.28</pre>

  <p>One notable versioning scheme where this approach gives an incorrect
  result is hex numbers (consider <code>A</code> vs <code>1A</code>). The
  simplest work around is to convert such numbers to decimal. Alternatively,
  one can fix the width of the hex number and pad all the values with leading
  zeros, for example: <code>00A</code> vs <code>01A</code>.</p>

  <p>It is also possible to convert the <i>upstream</i> and <i>prerel</i>
  parts into a <i>canonical representation</i> that will produce the correct
  comparison result when always compared lexicographically and as a whole.
  <span class="note">This can be useful, for example, when storing versions in
  the database which would otherwise require a custom collation implementation
  to obtain the correct sort order.</span></p>

  <p>To convert one of these parts to its canonical representation, all its
  string components are converted to the lower case while all its integer
  components are padded with leading zeros to the fixed length of
  <code>16</code> characters, with all trailing zero-only components removed.
  Note that this places an implementation limit on the length of integer
  components which should be checked by the implementation when converting to
  the canonical representation. <span class="note">The <code>16</code>
  characters limit was chosen to still be able to represent (with some spare)
  components in the <i>YYYYMMDDhhmmss</i> form while not (visually) bloating
  the database too much.</span> As a special case, the absent <i>prerel</i>
  part is represented as <code>~</code>. <span class="note">Since the ASCII
  code for <code>~</code> is greater than any other character that could
  appear in <i>prerel</i>, such a string will always be greater than any other
  representation.</span> The empty <i>prerel</i> part is represented as an
  empty string.</p>

  <p>Note that because it is not possible to perform a reverse conversion
  without the possibility of loss (consider <code>01.AA.BB</code>), the
  original parts may also have to be stored, for example, for display, to
  derive package archive names, etc.</p>

  <div class="note">
  <p>In quite a few contexts the implementation needs to ignore the
  <i>revision</i> and/or <i>iteration</i> parts. For example, this is needed
  to implement the semantics of newer revisions/iterations of packages
  replacing their old ones since we do not keep multiple revisions/iterations
  of the same upstream version in the same repository. As a result, in the
  package object model, we have a version key as just {<i>epoch</i>,
  <i>upstream</i>, <i>prerel</i>} but also store the package revision and
  iteration so that it can be shown to the user, etc.</p>
  </div>

  <h1 id="package-version-constraint">3 Package Version Constraint</h1>

  <p>The <code>bpkg</code> package version constraint may follow the package
  name in certain contexts, such as the manifest values and <code>bpkg</code>
  command line, to restrict the allowed package version set. It can be
  specified using comparison operators, shortcut (to range) operators, or
  ranges and has the following form:</p>

  <pre>&lt;version-constraint> = &lt;comparison> | &lt;shortcut> | &lt;range>
&lt;comparison>         = ('==' | '>' | '&lt;' | '>=' | '&lt;=') &lt;version>
&lt;shortcut>           = ('^' | '~') &lt;version>
&lt;range>              = ('(' | '[') &lt;version> &lt;version> (')' | ']')</pre>

  <p>The shortcut operators can only be used with <a
  href="../../build2/doc/build2-build-system-manual.xhtml#module-version">standard
  versions</a> (a semantic version without the pre-release part is a standard
  version). They are equivalent to the following ranges. <span
  class="note">The <code>X.Y.Z-</code> version signifies the earliest
  pre-release in the <code>X.Y.Z</code> series; see <a
  href="#package-version">Package Version</a> for details</span>.</p>

  <pre>~X.Y.Z  [X.Y.Z  X.Y+1.0-)

^X.Y.Z  [X.Y.Z  X+1.0.0-)  if X >  0
^0.Y.Z  [0.Y.Z  0.Y+1.0-)  if X == 0</pre>

  <p>That is, the tilde (<code>~</code>) constraint allows upgrades to any
  further patch version while the caret (<code>^</code>) constraint &#8211;
  also to any further minor version.</p>

  <div class="note">
  <p>Zero major version component is customarily used during early development
  where the minor version effectively becomes major. As a result, the tilde
  constraint has special semantics for this case.</p>
  </div>

  <p>Note that the shortuct operators can only be used with the complete,
  three-component versions (<code>X.Y.Z</code> with the optional pre-release
  part per the standard version). Specifically, there is no support for
  special <code>^X.Y</code> or <code>~X</code> semantics offered by some
  package manager &#8211; if desired, such functionality can be easily
  achieved with ranges. Also, the <code>0.0.Z</code> version is not considered
  special except as having zero major component for the tilde semantics
  discussed above.</p>

  <p>Note also that pre-releases do not require any special considerations
  when used with the shortcut operators. For example, if package
  <code>libfoo</code> is usable starting with the second beta of the
  <code>2.0.0</code> release, then our constraint could be expressed as:</p>

  <pre>libfoo ^2.0.0-b.2</pre>

  <div class="note">
  <p>Internally, shortcuts and comparisons can be represented as ranges (that
  is, <code>[v, v]</code> for <code>==</code>, <code>(v, inf)</code> for
  <code>></code>, etc). However, for display and serialization such
  representations should be converted back to simple operators. While it is
  possible that the original manifest specified equality or shortucts as full
  ranges, it is acceptable to display/serialize them as simpler operators.</p>
  </div>

  <p>Instead of a concrete value, the version in the constraint can be
  specified in terms of the dependent package's version (that is, the version
  of the package placing the constraint) using the special <code>$</code>
  value. For example:</p>

  <pre>libfoo == $</pre>

  <p>A constraint that contains <code>$</code> is called incomplete. This
  mechanism is primarily useful when developing related packages that should
  track each other's versions exactly or closely.</p>

  <p>In comparison operators and ranges the <code>$</code> value is replaced
  with the dependent version ignoring the revision. For shortcut operators,
  the dependent version must be a standard version and the following
  additional processing is applied depending on whether the version is a
  release, final pre-release, or a snapshot pre-release.</p>

  <ol>
  <li>For a release we set the min version patch to zero. For <code>^</code>
  we also set the minor version to zero, unless the major version is zero
  (reduces to <code>~</code>). The max version is set according to the
  standard shortcut logic. For example, <code>~$</code> is completed as
  follows:

  <pre>1.2.0 -> [1.2.0 1.3.0-)
1.2.1 -> [1.2.0 1.3.0-)
1.2.2 -> [1.2.0 1.3.0-)</pre>

  <p>And <code>^$</code> is completed as follows:</p>

  <pre>1.0.0 -> [1.0.0 2.0.0-)
1.1.1 -> [1.0.0 2.0.0-)</pre></li>

  <li>For a final pre-release the key observation is that if the patch
  component for <code>~</code> or minor and patch components for
  <code>^</code> are not zero, then that means there has been a compatible
  release and we treat this case the same as release, ignoring the pre-release
  part. If, however, it/they are zero, then that means there may yet be no
  final release and we have to start from the first alpha. For example, for
  the <code>~$</code> case:

  <pre>1.2.0-a.1 -> [1.2.0-a.1 1.3.0-)
1.2.0-b.2 -> [1.2.0-a.1 1.3.0-)
1.2.1-a.1 -> [1.2.0     1.3.0-)
1.2.2-b.2 -> [1.2.0     1.3.0-)</pre>

  <p>And for the <code>^$</code> case:</p>

  <pre>1.0.0-a.1 -> [1.0.0-a.1 2.0.0-)
1.0.0-b.2 -> [1.0.0-a.1 2.0.0-)
1.0.1-a.1 -> [1.0.0     2.0.0-)
1.1.0-b.2 -> [1.0.0     2.0.0-)</pre></li>

  <li>For a snapshot pre-release we distinguish two cases: a patch snapshot
  (the patch component is not zero) and a major/minor snapshot (the patch
  component is zero). For the patch snapshot case we assume that it is (most
  likely) developed independently of the dependency and we treat it the same
  as the final pre-release case. For example, if the dependent version is
  <code>1.2.1-a.0.nnn</code>, the dependency could be <code>1.2.0</code> or
  <code>1.2.2</code> (or somewhere in-between).

  <p>For the major/minor snapshot we assume that all the packages are
  developed in the lockstep and have the same <code>X.Y.0</code> version. In
  this case we make the range start from the earliest possible version in this
  "snapshot series" and end before the final pre-release. For example (in this
  case <code>~</code> and <code>^</code> are treated the same):</p>

  <pre>1.2.0-a.0.nnn -> [1.2.0-a.0.1 1.2.0-a.1)
2.0.0-b.2.nnn -> [2.0.0-b.2.1 2.0.0-b.3)</pre></li>
  </ol>

  <h1 id="package-skeleton">4 Package Build System Skeleton</h1>

  <p>There are situations where <code>bpkg</code> may need to evaluate
  <code>buildfile</code> expressions and fragments before committing to a
  particular version of the package and therefore before actually unpacking
  anything. For example, <code>bpkg</code> may need to evaluate a condition in
  the conditional dependency or it may need to negotiate a configuration among
  several dependents of a package which requires it to know this package's
  configuration variable types and default values.</p>

  <p>To solve this chicken and egg kind of problem, <code>bpkg</code> includes
  a minimal subset of the build system files along with the package's standard
  metadata (name, version, etc) into the repository metadata (<a
  href="#manifest-package-list-pkg"><code>packages.manifest</code></a>). This
  subset is called the package build system skeleton, or just package skeleton
  for short, and includes the <code>build/bootstrap.build</code> and
  <code>build/root.build</code> files (or their alternative naming scheme
  variants) as well as any files that may be sourced by
  <code>root.build</code>.</p>

  <p>The inclusion of <code>build/bootstrap.build</code> and
  <code>build/root.build</code> (if present) as well as any
  <code>build/config/*.build</code> (or their alternative naming scheme
  variants) is automatic. However, if <code>root.build</code> sources any
  files other than <code>build/config/*.build</code>, then they must be
  specified explicitly in the package manifest using the <a
  href="#manifest-package-build-file"><code>build-file</code></a> value.</p>

  <p>Inside these buildfiles the skeleton load can be distinguished from
  normal load by examining the <code>build.mode</code> variable, which is set
  to <code>skeleton</code> during the skeleton load. In particular, this
  variable must be used to omit loading of build system modules that are
  neither built-in nor standard pre-installed and which are therefore listed
  as package dependencies. Such modules are not yet available during the
  skeleton load. For example:</p>

  <pre># root.build

using cxx       # Ok, built-in module.
using autoconf  # Ok, standard pre-installed module.

if ($build.mode != 'skeleton')
  using hello</pre>

  <p>The <code>build.mode</code> variable can also be used to omit parts of
  <code>root.build</code> that are expensive to evaluate and which are only
  necessary during the actual build. Here is a realistic example:</p>

  <pre># root.build

...

using cxx

# Determine the GCC plugin directory. But omit doing it during the
# skeleton load.
#
if ($build.mode != 'skeleton')
{
  if ($cxx.id != 'gcc')
    fail 'this project can only be built with GCC'

  # If plugin support is disabled, then -print-file-name will print
  # the name we have passed (the real plugin directory will always
  # be absolute).
  #
  plugin_dir = [dir_path] \
    $process.run($cxx.path -print-file-name=plugin)

  if ("$plugin_dir" == plugin)
    fail "$recall($cxx.path) does not support plugins"

  plugin_dir = $normalize($plugin_dir)
}</pre>

  <h1 id="dep-config-negotiation">5 Dependency Configuration Negotiation</h1>

  <p>In <code>bpkg</code>, a dependent package may specify a desired
  configuration for a dependency package. Because there could be multiple such
  dependents, <code>bpkg</code> needs to come up with a dependency
  configuration that is acceptable to all of them. This process is called the
  dependency configuration negotiation.</p>

  <p>The desired dependency configuration is specified as part of the <a
  href="#manifest-package-depends"><code>depends</code></a> manifest value and
  can be expressed as either a single <code>require</code> clause or as a pair
  of <code>prefer</code>/<code>accept</code> clauses.</p>

  <p>The <code>require</code> clause is essentially a shortcut for specifying
  the <code>prefer</code>/<code>accept</code> clauses where the
  <code>accept</code> condition simply verifies all the variable values
  assigned in the <code>prefer</code> clause. It is, however, further
  restricted to the common case of only setting <code>bool</code> variables
  and only to <code>true</code> to allow additional optimizations during the
  configuration negotiation. The remainder of this section only deals with the
  general <code>prefer</code>/<code>accept</code> semantics.</p>

  <p>While the exact format of <code>prefer</code>/<code>accept</code> is
  described as part of the <a
  href="#manifest-package-depends"><code>depends</code></a> manifest value,
  for this section it is sufficient to know that the <code>prefer</code>
  clause is an arbitrary <code>buildfile</code> fragment that is expected to
  set one or more dependency configuration variables to the values preferred
  by this dependent while the <code>accept</code> clause is a
  <code>buildfile</code> eval context expression that should evaluate to
  <code>true</code> or <code>false</code> indicating whether the dependency
  configuration values it is evaluated on are acceptable to this dependent.
  For example:</p>

  <pre>libfoo ^1.0.0
{
  # We prefer the cache but can work without it.
  # We need the buffer of at least 4KB.
  #
  prefer
  {
    config.libfoo.cache = true

    config.libfoo.buffer = ($config.libfoo.buffer &lt; 4096 \
                            ? 4096                       \
                            : $config.libfoo.buffer)
  }

  accept ($config.libfoo.buffer >= 4096)
}</pre>

  <p>The configuration negotiation algorithm can be summarized as cooperative
  refinement. Specifically, whenever a <code>prefer</code> clause of a
  dependent changes any configuration value, all other dependents'
  <code>prefer</code> clauses are re-evaluated. This process continues until
  there are no more changes (success), one of the <code>accept</code> clauses
  returned <code>false</code> (failure), or the process starts "yo-yo'ing"
  between two or more configurations (failure).</p>

  <p>The dependents are expected to cooperate by not overriding "better"
  values that were set by other dependents. Consider the following two
  <code>prefer</code> clauses:</p>

  <pre>prefer
{
  config.libfoo.buffer = 4096
}

prefer
{
  config.libfoo.buffer = ($config.libfoo.buffer &lt; 4096 \
                          ? 4096                       \
                          : $config.libfoo.buffer)
}</pre>

  <p>The first version is non-cooperative and should only be used if this
  dependent requires the buffer to be exactly 4KB. The second version is
  cooperative: it will increase the buffer to the minimum required by this
  dependent but will respect values above 4KB.</p>

  <p>One case where we don't need to worry about this is when setting the
  configuration variable to the "best" possible value. One common example of
  this is setting a <code>bool</code> configuration to <code>true</code>.</p>

  <p>With a few exceptions discussed below, a dependent must always re-set the
  configuration variable, even if to the better value. For example, the
  following is an incorrect attempt at the above cooperative
  <code>prefer</code> clause:</p>

  <pre>prefer
{
  if ($config.libfoo.buffer &lt; 4096)  # Incorrect.
    config.libfoo.buffer = 4096
}</pre>

  <p>The problem with the above attempt is that the default value could be
  greater than 4KB, in which case <code>bpkg</code> will have no idea that
  there is a dependent relying on this configuration value.</p>

  <p>Before each <code>prefer</code> clause re-evaluation, variables that were
  first set to their current values by this dependent are reset to their
  defaults thus allowing the dependent to change its mind, for instance, in
  response to other configuration changes. For example:</p>

  <pre># While we have no preference about the cache, if enabled/disabled,
# we need a bigger/smaller buffer.
#
prefer
{
  min_buffer = ($config.libfoo.cache ? 8192 : 4096)

  config.libfoo.buffer = ($config.libfoo.buffer &lt; $min_buffer \
                          ? $min_buffer                       \
                          : $config.libfoo.buffer)
}

accept ($config.libfoo.buffer >= ($config.libfoo.cache ? 8192 : 4096))</pre>

  <p>The interesting case to consider in the above example is when
  <code>config.libfoo.cache</code> changes from <code>true</code> to
  <code>false</code>: without the reset to defaults semantics the
  <code>prefer</code> clause would have kept the buffer at 8KB (since it's
  greater than the 4KB minimum).</p>

  <div class="note">
  <p>Currently <code>accept</code> is always evaluated after
  <code>prefer</code> and temporary variables (like <code>min_buffer</code> in
  the above example) set in <code>prefer</code> are visible in
  <code>accept</code>. But it's best not to rely on this in case it changes in
  the future. For example, we may try harder to resolve the "yo-yo'ing" case
  mentioned above by checking if one of the alternating configurations are
  acceptable to everyone without re-evaluation.</p>

  <p>This is also the reason why we need a separate <code>accept</code> in the
  first place. Plus, it allows for more advanced configuration techniques
  where we may need to have an acceptance criteria but no preferences.</p>
  </div>

  <p>Configuration variables that are set by the dependent in the
  <code>prefer</code> clause are visible in the subsequent clauses as well as
  in the subsequent <code>depends</code> values of this dependent.
  Configuration variables that are not set, however, are only visible until
  the immediately following <code>reflect</code> clause. For example, in the
  above listing, <code>config.libfoo.cache</code> would still be visible in
  the <code>reflect</code> clause if it were to follow <code>accept</code> but
  no further. As a result, if we need to make decisions based on configuration
  variables that we have no preference about, they need to be saved in the
  <code>reflect</code> clause. For example:</p>

  <pre>depends:
\
libfoo ^1.0.0
{
  # We have no preference about the cache but need to
  # observe its value.
  #
  prefer
  {
  }

  accept (true)

  reflect
  {
    config.hello.libfoo_cache = $config.libfoo.cache
  }
}
\

depends: libbar ^1.0.0 ? ($config.hello.libfoo_cache)</pre>

  <p>It is possible to determine the origin of the configuration variable
  value using the <code>$config.origin()</code> function. It returns either
  <code>undefined</code> if the variable is undefined (only possible if it has
  no default value), <code>default</code> if the variable has the default
  value from the <code>config</code> directive in <code>root.build</code>,
  <code>buildfile</code> if the value is from a <code>buildfile</code>,
  normally <code>config.build</code>, or <code>override</code> if the value is
  a command line override (that is, user configuration). For example, this is
  how we could use it if we only wanted to change the default value (notice
  that it's the variable's name and not its <code>$</code>-expansion that we
  pass to <code>$config.origin()</code>):</p>

  <pre>prefer
{
  config.libfoo.buffer = (                            \
    $config.origin(config.libfoo.buffer) == 'default' \
    ? 4096                                            \
    : $config.libfoo.buffer)
}</pre>

  <p>The following sub-sections discuss a number of more advanced
  configuration techniques that are based on the functionality described in
  this section.</p>

  <h2 id="dep-config-prefer-x-accept-xy">5.1 Prefer X but Accept X or Y</h2>

  <p>Consider a configuration variable that is a choice between several
  mutually exclusive values, for example, user interface backends that could
  be, say, <code>cli</code>, <code>gui</code>, or <code>none</code>. In such
  situations it's common to prefer one value but being able to work with some
  subset of them. For example, we could prefer <code>gui</code> but were also
  able to make do with <code>cli</code> but not with <code>none</code>. Here
  is how we could express such a configuration:</p>

  <pre>libfoo ^1.0.0
{
  # We prefer `gui`, can also work with `cli` but not `none`.
  #
  prefer
  {
    config.libfoo.ui = (                                         \
      $config.origin(config.libfoo.ui) == 'default' ||           \
      ($config.libfoo.ui != 'gui' &amp;&amp; $config.libfoo.ui != 'cli') \
      ? 'gui'                                                    \
      : $config.libfoo.ui)
  }

  accept ($config.libfoo.ui == 'gui' || $config.libfoo.ui == 'cli')
}</pre>

  <h2 id="dep-config-use-if-enabled">5.2 Use If Enabled</h2>

  <p>Sometimes we may want to use a feature if it is enabled by someone else
  but not enable it ourselves. For example, the feature might be expensive and
  our use of it tangential, but if it's enabled anyway, then we might as well
  take advantage of it. Here is how we could express such a configuration:</p>

  <pre>libfoo ^1.0.0
{
  # Use config.libfoo.x only if enabled by someone else.
  #
  prefer
  {
  }

  accept (true)

  reflect
  {
    config.hello.libfoo_x = $config.libfoo.x
  }
}</pre>

  <h2 id="dep-config-disable-default">5.3 Disable If Enabled by Default</h2>

  <p>Sometimes we may want to disable a feature that is enabled by default
  provided that nobody else needs it. For example, the feature might be
  expensive and we would prefer to avoid paying the cost if we are the only
  ones using this dependency. Here is how we could express such a
  configuration:</p>

  <pre>libfoo ^1.0.0
{
  prefer
  {
    if ($config.origin(config.libfoo.x) == 'default')
      config.libfoo.x = false
  }

  accept (true)
}</pre>

  <h1 id="manifests">6 Manifests</h1>

  <p>This chapter describes the general manifest file format as well as the
  concrete manifests used by <code>bpkg</code>.</p>

  <p>Currently, three manifests are defined: package manifest, repository
  manifest, and signature manifest. The former two manifests can also be
  combined into a list of manifests to form the list of available packages and
  the description of a repository, respectively.</p>

  <h2 id="manifest-format">6.1 Manifest Format</h2>

  <p>A manifest is a UTF-8 encoded text restricted to the Unicode graphic
  characters, tabs (<code>\t</code>), carriage returns (<code>\r</code>), and
  line feeds (<code>\n</code>). It contains a list of name-value pairs in the
  form:</p>

  <pre>&lt;name>: &lt;value></pre>

  <p>For example:</p>

  <pre>name: libfoo
version: 1.2.3</pre>

  <div class="note">
  <p>If a value needs to be able to contain other Unicode codepoints, they
  should be escaped in a value-specific manner. For example, the backslash
  (<code>\</code>) escaping described below can be extended for this
  purpose.</p>
  </div>

  <p>The name can contain any characters except <code>:</code> and
  whitespaces. Newline terminates the pair unless escaped with <code>\</code>
  (see below). Leading and trailing whitespaces before and after name and
  value are ignored except in the multi-line mode (see below).</p>

  <p>If the first non-whitespace character on the line is <code>#</code>, then
  the rest of the line is treated as a comment and ignored except if the
  preceding newline was escaped or in the multi-line mode (see below). For
  example:</p>

  <pre># This is a comment.
short: This is #not a comment
long: Also \
#not a comment</pre>

  <p>The first name-value pair in the manifest file should always have an
  empty name. The value of this special pair is the manifest format version.
  The version value shall use the default (that is, non-multi-line) mode and
  shall not use any escape sequences. Currently it should be <code>1</code>,
  for example:</p>

  <pre>: 1
name: libfoo
version: 1.2.3</pre>

  <p>Any new name that is added without incrementing the version must be
  optional so that it can be safely ignored by older implementations.</p>

  <p>The special empty name pair can also be used to separate multiple
  manifests. In this case the version may be omitted in the subsequent
  manifests, for example:</p>

  <pre>: 1
name: libfoo
version: 1.2.3
:
name: libbar
version: 2.3.4</pre>

  <p>To disable treating of a newline as a name-value pair terminator we can
  escape it with <code>\</code>. Note that <code>\</code> is only treated as
  an escape sequence when followed by a newline and both are simply removed
  from the stream (as opposed to being replaced with a space). To enter a
  literal <code>\</code> at the end of the value, use the <code>\\</code>
  sequence. For example:</p>

  <pre>description: Long text that doesn't fit into one line \
so it is continued on the next line.</pre>

  <pre>windows-path: C:\foo\bar\\</pre>

  <p>Notice that in the final example only the last <code>\</code> needs
  special handling since it is the only one that is followed by a newline.</p>

  <p>One may notice that in this newline escaping scheme a line consisting of
  just <code>\</code> followed by a newline has no use, except, perhaps, for
  visual presentation of, arguably, dubious value. For example, this
  representation:</p>

  <pre>description: First line. \
\
Second line.</pre>

  <p>Is semantically equivalent to:</p>

  <pre>description: First line. Second line.</pre>

  <p>As a result, such a sequence is "overloaded" to provide more useful
  functionality in two ways: Firstly, if <code>:</code> after the name is
  followed on the next line by just <code>\</code> and a newline, then it
  signals the start of the multi-line mode. In this mode all subsequent
  newlines and <code>#</code> are treated as ordinary characters rather than
  value terminators or comments until a line consisting of just <code>\</code>
  and a newline (the multi-line mode terminator). For example:</p>

  <pre>description:
\
First paragraph.
#
Second paragraph.
\</pre>

  <p>Expressed as a C-string, the value in the above example is:</p>

  <pre>"First paragraph.\n#\nSecond paragraph."</pre>

  <div class="note">
  <p>Originally, the multi-line mode was entered if <code>:</code> after the
  name were immediately followed by <code>\</code> and a newline but on the
  same line. While this syntax is still recognized for backwards
  compatibility, it is deprecated and will be discontinued in the future.</p>
  </div>

  <p>Note that in the multi-line mode we can still use newline escaping to
  split long lines, for example:</p>

  <pre>description:
\
First paragraph that doesn't fit into one line \
so it is continued on the next line.
Second paragraph.
\</pre>

  <p>And secondly, in the simple (that is, non-multi-line) mode, the sole
  <code>\</code> and newline sequence is overloaded to mean a newline. So the
  previous example can also be represented like this:</p>

  <pre>description: First paragraph that doesn't fit into one \
line so it is continued on the next line.\
\
Second paragraph.</pre>

  <p>Note that the multi-line mode can be used to capture a value with leading
  and/or trailing whitespaces, for example:</p>

  <pre>description:
\
  test

\</pre>

  <p>The C-string representing this value is:</p>

  <pre>"  test\n"</pre>

  <p>EOF can be used instead of a newline to terminate both simple and
  multi-line values. For example the following representation results in the
  same value as in the previous example.</p>

  <pre>description:
\
  test

&lt;EOF></pre>

  <p>By convention, names are all in lower case and multi-word names are
  separated with <code>-</code>. Note that names are case-sensitive.</p>

  <p>Also by convention, the following name suffixes are used to denote common
  types of values:</p>

  <pre>-file
-url
-email</pre>

  <p>For example:</p>

  <pre>description: Inline description
description-file: README
package-url: http://www.example.com
package-email: john@example.com</pre>

  <p>Other common name suffixes (such as -feed) could be added later.</p>

  <div class="note">
  <p>Generally, unless there is a good reason not to, we keep values
  lower-case (for example, <code>requires</code> values such as
  <code>c++11</code> or <code>linux</code>). An example where we use
  upper/mixed case would be <code>license</code>; it seems unlikely
  <code>gplv2</code> would be better than <code>GPLv2</code>.</p>
  </div>

  <p>A number of name-value pairs described below allow for the value proper
  to be optionally followed by <code>;</code> and a comment. Such comments
  serve as additional documentation for the user and should be one or more
  full sentences, that is start with a capital letter and end with a period.
  Note that unlike <code>#</code>-style comments which are ignored, these
  comments are considered to be part of the value. For example:</p>

  <pre>email: foo-users@example.com ; Public mailing list.</pre>

  <p>It is recommended that you keep comments short, single-sentence. Note
  that non-comment semicolons in such values have to be escaped with a
  backslash, for example:</p>

  <pre>url: http://git.example.com/?p=foo\;a=tree</pre>

  <p>The only other recognized escape sequence in such values is
  <code>\\</code>, which is replaced with a single backslash. If a backslash
  is followed by any other character, then it is treated literally.</p>

  <p>If a value with a comment is multi-line, then <code>;</code> must appear
  on a separate line, for example:</p>

  <pre>url:
\
http://git.example.com/?p=foo;a=tree
;
Git repository tree.
\</pre>

  <p>In this case, only lines that consist of a sole non-comment semicolon
  need escaping, for example:</p>

  <pre>license:
\
other: strange
\;
license
\</pre>

  <p>The only other recognized escape sequence in such multi-line values is
  lines consisting of two or more backslashes followed by a semicolon.</p>

  <p>In the manifest specifications described below optional components are
  enclosed in square brackets (<code>[]</code>). If the name is enclosed in
  <code>[]</code> then the name-value pair is optional, otherwise &#8211;
  required. For example:</p>

  <pre>name: &lt;name>
license: &lt;licenses> [; &lt;comment>]
[description]: &lt;text></pre>

  <p>In the above example <code>name</code> is required, <code>license</code>
  has an optional component (comment), and <code>description</code> is
  optional.</p>

  <p>In certain situations (for example, shell scripts) it can be easier to
  parse the binary manifest representation. The binary representation does not
  include comments and consists of a sequence of name-value pairs in the
  following form:</p>

  <pre>&lt;name>:&lt;value>\0</pre>

  <p>That is, the name and the value are separated by a colon and each pair
  (including the last) is terminated with the <code>NUL</code> character. Note
  that there can be no leading or trailing whitespace characters around the
  name and any whitespaces after the colon and before the <code>NUL</code>
  terminator are part of the value. Finally, the manifest format versions are
  always explicit (that is, not empty) in binary manifest lists.</p>

  <h2 id="manifest-package">6.2 Package Manifest</h2>

  <p>The package manifest (the <code>manifest</code> file found in the
  package's root directory) describes a <code>bpkg</code> package. The
  manifest synopsis is presented next followed by the detailed description of
  each value in subsequent sections.</p>

  <p>The subset of the values up to and including <code>license</code>
  constitute the package manifest header. Note that the header is a valid
  package manifest since all the other values are optional. There is also no
  requirement for the header values to appear first or to be in a specific
  order. In particular, in a full package manifest they can be interleaved
  with non-header values.</p>

  <pre>name: &lt;name>
version: &lt;version>
[upstream-version]: &lt;string>
[type]: &lt;type>
[language]: &lt;lang>
[project]: &lt;name>
[priority]: &lt;priority> [; &lt;comment>]
summary: &lt;text>
license: &lt;licenses> [; &lt;comment>]</pre>

  <pre>[topics]: &lt;topics>
[keywords]: &lt;keywords>
[description]: &lt;text>
[description-file]: &lt;path> [; &lt;comment>]
[description-type]: &lt;text-type>
[package-description]: &lt;text>
[package-description-file]: &lt;path> [; &lt;comment>]
[package-description-type]: &lt;text-type>
[changes]: &lt;text>
[changes-file]: &lt;path> [; &lt;comment>]
[changes-type]: &lt;text-type>

[url]: &lt;url> [; &lt;comment>]
[doc-url]: &lt;url> [; &lt;comment>]
[src-url]: &lt;url> [; &lt;comment>]
[package-url]: &lt;url> [; &lt;comment>]

[email]: &lt;email> [; &lt;comment>]
[package-email]: &lt;email> [; &lt;comment>]
[build-email]: &lt;email> [; &lt;comment>]
[build-warning-email]: &lt;email> [; &lt;comment>]
[build-error-email]: &lt;email> [; &lt;comment>]

[depends]: [*] &lt;alternatives> [; &lt;comment>]
[requires]: [*] &lt;alternatives> [; &lt;comment>]

[tests]: [*] &lt;name> [&lt;version-constraint>]
[examples]: [*] &lt;name> [&lt;version-constraint>]
[benchmarks]: [*] &lt;name> [&lt;version-constraint>]

[builds]: &lt;class-expr> [; &lt;comment>]
[build-include]: &lt;config>[/&lt;target>] [; &lt;comment>]
[build-exclude]: &lt;config>[/&lt;target>] [; &lt;comment>]
[build-auxiliary]: &lt;config> [; &lt;comment>]
[build-auxiliary-&lt;name>]: &lt;config> [; &lt;comment>]
[build-bot]: &lt;pub-key>

[*-build-config]: &lt;args> [; &lt;comment>]

[*-builds]: &lt;class-expr> [; &lt;comment>]
[*-build-include]: &lt;config>[/&lt;target>] [; &lt;comment>]
[*-build-exclude]: &lt;config>[/&lt;target>] [; &lt;comment>]
[*-build-auxiliary]: &lt;config> [; &lt;comment>]
[*-build-auxiliary-&lt;name>]: &lt;config> [; &lt;comment>]
[*-build-bot]: &lt;pub-key>

[*-build-email]: &lt;email> [; &lt;comment>]
[*-build-warning-email]: &lt;email> [; &lt;comment>]
[*-build-error-email]: &lt;email> [; &lt;comment>]

[build-file]: &lt;path>

[bootstrap-build]: &lt;text>
[root-build]: &lt;text>
[*-build]: &lt;text>

[bootstrap-build2]: &lt;text>
[root-build2]: &lt;text>
[*-build2]: &lt;text>

[*-name]: &lt;name> [&lt;name>...]
[*-version]: &lt;string>
[*-to-downstream-version]: &lt;regex></pre>

  <h3 id="manifest-package-name">6.2.1 <code>name</code></h3>

  <pre>name: &lt;name></pre>

  <p>The package name. See <a href="#package-name">Package Name</a> for the
  package name format description. Note that the name case is preserved for
  display, in file names, etc.</p>

  <h3 id="manifest-package-version">6.2.2 <code>version</code></h3>

  <pre>version: &lt;version>
[upstream-version]: &lt;string></pre>

  <p>The package version. See <a href="#package-version">Package Version</a>
  for the version format description. Note that the version case is preserved
  for display, in file names, etc.</p>

  <p>When packaging existing projects, sometimes you may want to deviate from
  the upstream versioning scheme because, for example, it may not be
  representable as a <code>bpkg</code> package version or simply be
  inconvenient to work with. In this case you would need to come up with an
  upstream-to-downstream version mapping and use the
  <code>upstream-version</code> value to preserve the original version for
  information.</p>

  <h3 id="manifest-package-type-language">6.2.3 <code>type</code>,
  <code>language</code></h3>

  <pre>[type]: &lt;type>
[language]: &lt;lang>

&lt;type> = &lt;name>[,&lt;sub-options>]
&lt;lang> = &lt;name>[=impl]</pre>

  <p>The package type and programming language(s).</p>

  <p>The currently recognized package types are <code>exe</code>,
  <code>lib</code>, and <code>other</code>. If the type is not specified, then
  if the package name starts with <code>lib</code>, then it is assumed to be
  <code>lib</code> and <code>exe</code> otherwise (see <a
  href="#package-name">Package Name</a> for details). Other package types may
  be added in the future and code that does not recognize a certain package
  type should treat it as <code>other</code>. The type name can be followed by
  a comma-separated list of sub-options. Currently, the only recognized
  sub-option is <code>binless</code> which applies to the <code>lib</code>
  type indicating a header-only (or equivalent) library. For example:</p>

  <pre>type: lib,binless</pre>

  <p>The package language must be in the lower case, for example,
  <code>c</code>, <code>c++</code>, <code>rust</code>, <code>bash</code>. If
  the language is not specified, then if the package name has an extension (as
  in, for example, <code>libbutl.bash</code>; see <a
  href="#package-name">Package Name</a> for details) the extension is assumed
  to name the package language. Otherwise, <code>cc</code> (unspecified
  <code>c</code>-common language) is assumed. If a package uses multiple
  languages, then multiple <code>language</code> values must be specified. The
  languages which are only used in a library's implementation (as opposed to
  also in its interface) should be marked as such. For example, for a C
  library with C++ implementation:</p>

  <pre>type: lib
language: c
language: c++=impl</pre>

  <div class="note">
  <p>If the use of a language, such as C++, also always implies the use of
  another language, such as C, then such an implied language need not be
  explicitly specified.</p>
  </div>

  <h3 id="manifest-package-project">6.2.4 <code>project</code></h3>

  <pre>[project]: &lt;name></pre>

  <p>The project this package belongs to. The project name has the same
  restrictions as the package name (see <a href="#package-name">Package
  Name</a> for details) and its case is preserved for display, in directory
  names, etc. If unspecified, then the project name is assumed to be the same
  as the package name.</p>

  <p>Projects are used to group related packages together in order to help
  with organization and discovery in repositories. For example, packages
  <code>hello</code>, <code>libhello</code>, and <code>libhello2</code> could
  all belong to project <code>hello</code>. By convention, projects of library
  packages are named without the <code>lib</code> prefix.</p>

  <h3 id="manifest-package-">6.2.5 <code>priority</code></h3>

  <pre>[priority]: &lt;priority> [; &lt;comment>]

&lt;priority> = security | high | medium | low</pre>

  <p>The release priority (optional). As a guideline, use
  <code>security</code> for security fixes, <code>high</code> for critical bug
  fixes, <code>medium</code> for important bug fixes, and <code>low</code> for
  minor fixes and/or feature releases. If not specified, <code>low</code> is
  assumed.</p>

  <h3 id="manifest-package-summary">6.2.6 <code>summary</code></h3>

  <pre>summary: &lt;text></pre>

  <p>The short description of the package.</p>

  <h3 id="manifest-package-license">6.2.7 <code>license</code></h3>

  <pre>license: &lt;licenses> [; &lt;comment>]

&lt;licenses> = &lt;license> [, &lt;license>]*
&lt;license>  = [&lt;scheme>:] &lt;name>
&lt;scheme>   = other</pre>

  <p>The package license. The default license name scheme is <a
  href="https://spdx.org/licenses/">SPDX License Expression</a>. In its
  simplest form, it is just an ID of the license under which this package is
  distributed. An optional comment normally gives the full name of the
  license, for example:</p>

  <pre>license: MPL-2.0 ; Mozilla Public License 2.0</pre>

  <p>The following table lists the most commonly used free/open source
  software licenses and their SPDX license IDs:</p>

  <pre>MIT                ; MIT License.

BSD-2-Clause       ; BSD 2-Clause "Simplified" License
BSD-3-Clause       ; BSD 3-Clause "New" or "Revised" License
BSD-4-Clause       ; BSD 4-Clause "Original" or "Old" License

GPL-2.0-only       ; GNU General Public License v2.0 only
GPL-2.0-or-later   ; GNU General Public License v2.0 or later
GPL-3.0-only       ; GNU General Public License v3.0 only
GPL-3.0-or-later   ; GNU General Public License v3.0 or later

LGPL-2.0-only      ; GNU Library General Public License v2 only
LGPL-2.0-or-later  ; GNU Library General Public License v2 or later
LGPL-2.1-only      ; GNU Lesser General Public License v2.1 only
LGPL-2.1-or-later  ; GNU Lesser General Public License v2.1 or later
LGPL-3.0-only      ; GNU Lesser General Public License v3.0 only
LGPL-3.0-or-later  ; GNU Lesser General Public License v3.0 or later

AGPL-3.0-only      ; GNU Affero General Public License v3.0 only
AGPL-3.0-or-later  ; GNU Affero General Public License v3.0 or later

Apache-1.0         ; Apache License 1.0
Apache-1.1         ; Apache License 1.1
Apache-2.0         ; Apache License 2.0

MPL-1.0            ; Mozilla Public License 1.0
MPL-1.1            ; Mozilla Public License 1.1
MPL-2.0            ; Mozilla Public License 2.0

BSL-1.0            ; Boost Software License 1.0

Unlicense          ; The Unlicense (public domain)</pre>

  <p>If the package is licensed under multiple licenses, then an SPDX license
  expression can be used to specify this, for example:</p>

  <pre>license: Apache-2.0 OR MIT
license: MIT AND BSD-2-Clause</pre>

  <p>A custom license or extra conditions can be expressed either using the
  license reference mechanism of the SPDX license expression or using the
  <code>other</code> scheme (described below). For example:</p>

  <pre>license: LicenseRef-My-MIT-Like; Custom MIT-alike license
license: other: MIT with extra attribution requirements</pre>

  <p>The <code>other</code> license name scheme can be used to specify
  licenses that are not defined by SPDX. The license names in this scheme are
  free form with case-insensitive comparison. The following names in this
  scheme have predefined meaning:</p>

  <pre>other: public domain    ; Released into the public domain
other: available source ; Not free/open source with public source code
other: proprietary      ; Not free/open source
other: TODO             ; License is not yet decided</pre>

  <div class="note">
  <p>For new projects <a href="https://unlicense.org">The Unlicense</a>
  disclaimer with the <code>Unlicense</code> SPDX ID is recommended over
  <code>other: public domain</code>.</p>
  </div>

  <p>To support combining license names that use different schemes, the
  <code>license</code> manifest value can contain a comma-separated list of
  license names. This list has the <i>AND</i> semantics, that is, the user
  must comply with all the licenses listed. To capture alternative licensing
  options (the <i>OR</i> semantics), multiple <code>license</code> manifest
  values are used, for example:</p>

  <pre>license: GPL-2.0-only, other: available source
license: other: proprietary</pre>

  <p>For complex licensing situations it is recommended to add comments as an
  aid to the user, for example:</p>

  <pre>license: LGPL-2.1-only AND MIT ; If linking with GNU TLS.
license: BSD-3-Clause          ; If linking with OpenSSL.</pre>

  <div class="note">
  <p>For backwards compatibility with existing packages, the following
  (deprecated) scheme-less values on the left are recognized as aliases for
  the new values on the right:</p>

  <pre>BSD2               BSD-2-Clause
BSD3               BSD-3-Clause
BSD4               BSD-4-Clause
GPLv2              GPL-2.0-only
GPLv3              GPL-3.0-only
LGPLv2             LGPL-2.0-only
LGPLv2.1           LGPL-2.1-only
LGPLv3             LGPL-3.0-only
AGPLv3             AGPL-3.0-only
ASLv1              Apache-1.0
ASLv1.1            Apache-1.1
ASLv2              Apache-2.0
MPLv2              MPL-2.0

public domain      other: public domain
available source   other: available source
proprietary        other: proprietary
TODO               other: TODO</pre>
  </div>

  <h3 id="manifest-package-topics">6.2.8 <code>topics</code></h3>

  <pre>[topics]: &lt;topics>

&lt;topics> = &lt;topic> [, &lt;topic>]*</pre>

  <p>The package topics (optional). The format is a comma-separated list of up
  to five potentially multi-word concepts that describe this package. For
  example:</p>

  <pre>topics: xml parser, xml serializer</pre>

  <h3 id="manifest-package-keywords">6.2.9 <code>keywords</code></h3>

  <pre>[keywords]: &lt;keywords>

&lt;keywords> = &lt;keyword> [ &lt;keyword>]*</pre>

  <p>The package keywords (optional). The format is a space-separated list of
  up to five words that describe this package. Note that the package and
  project names as well as words from its summary are already considered to be
  keywords and need not be repeated in this value.</p>

  <h3 id="manifest-package-description">6.2.10 <code>description</code>,
  <code>package-description</code></h3>

  <pre>[description]: &lt;text>
[description-file]: &lt;path> [; &lt;comment>]
[description-type]: &lt;text-type>
[package-description]: &lt;text>
[package-description-file]: &lt;path> [; &lt;comment>]
[package-description-type]: &lt;text-type></pre>

  <p>The detailed description of the project (<code>description</code>) and
  package (<code>package-description</code>). If the package description is
  not specified, it is assumed to be the same as the project description. It
  only makes sense to specify the <code>package-description</code> value if
  the project and package are maintained separately. A description can be
  provided either inline as a text fragment or by referring to a file within a
  package (for example, <code>README</code>), but not both. For
  <code>package-description-file</code> the recommended file name is
  <code>PACKAGE-README</code> or <code>README-PACKAGE</code>.</p>

  <p>In the web interface (<code>brep</code>) the description is displayed
  according to its type. Currently, pre-formatted plain text, <a
  href="https://github.github.com/gfm">GitHub-Flavored Markdown</a>, and <a
  href="https://spec.commonmark.org/current">CommonMark</a> are supported with
  the following <code>*-type</code> values, respectively:</p>

  <pre>text/plain
text/markdown;variant=GFM
text/markdown;variant=CommonMark</pre>

  <p>If just <code>text/markdown</code> is specified, then the GitHub-Flavored
  Markdown (which is a superset of CommonMark) is assumed.</p>

  <p>If a description type is not explicitly specified and the description is
  specified as <code>*-file</code>, then an attempt to derive the type from
  the file extension is made. Specifically, the <code><b>.md</b></code> and
  <code><b>.markdown</b></code> extensions are mapped to
  <code>text/markdown</code>, the <code><b>.txt</b></code> and no extension
  are mapped to <code>text/plain</code>, and all other extensions are treated
  as an unknown type, similar to unknown <code>*-type</code> values. And if a
  description is not specified as a file, <code>text/plain</code> is
  assumed.</p>

  <h3 id="manifest-package-changes">6.2.11 <code>changes</code></h3>

  <pre>[changes]: &lt;text>
[changes-file]: &lt;path> [; &lt;comment>]
[changes-type]: &lt;text-type></pre>

  <p>The description of changes in the release.</p>

  <div class="note">
  <p>The tricky aspect is what happens if the upstream release stays the same
  (and has, say, a <code>NEWS</code> file to which we point) but we need to
  make another package release, for example, to apply a critical patch.</p>
  </div>

  <p>Multiple <code>changes</code> values can be present which are all
  concatenated in the order specified, that is, the first value is considered
  to be the most recent (similar to <code>ChangeLog</code> and
  <code>NEWS</code> files). For example:</p>

  <pre>changes: 1.2.3-2: applied upstream patch for critical bug bar
changes: 1.2.3-1: applied upstream patch for critical bug foo
changes-file: NEWS</pre>

  <p>Or:</p>

  <pre>changes:
\
1.2.3-2
  - applied upstream patch for critical bug bar
  - regenerated documentation

1.2.3-1
  - applied upstream patch for critical bug foo
\
changes-file: NEWS</pre>

  <p>In the web interface (<code>brep</code>) the changes are displayed
  according to their type, similar to the package description (see the <a
  href="#manifest-package-description"><code>description</code></a> value for
  details). If the changes type is not explicitly specified, then the types
  deduced for individual <code>changes</code> values must all be the same.</p>

  <h3 id="manifest-package-url">6.2.12 <code>url</code></h3>

  <pre>[url]: &lt;url> [; &lt;comment>]</pre>

  <p>The project home page URL.</p>

  <h3 id="manifest-package-doc-url">6.2.13 <code>doc-url</code></h3>

  <pre>[doc-url]: &lt;url> [; &lt;comment>]</pre>

  <p>The project documentation URL.</p>

  <h3 id="manifest-package-src-url">6.2.14 <code>src-url</code></h3>

  <pre>[src-url]: &lt;url> [; &lt;comment>]</pre>

  <p>The project source repository URL.</p>

  <h3 id="manifest-package-package-url">6.2.15 <code>package-url</code></h3>

  <pre>[package-url]: &lt;url> [; &lt;comment>]</pre>

  <p>The package home page URL. If not specified, then assumed to be the same
  as <code>url</code>. It only makes sense to specify this value if the
  project and package are maintained separately.</p>

  <h3 id="manifest-package-email">6.2.16 <code>email</code></h3>

  <pre>[email]: &lt;email> [; &lt;comment>]</pre>

  <p>The project email address. For example, a support mailing list.</p>

  <h3 id="manifest-package-package-email">6.2.17
  <code>package-email</code></h3>

  <pre>[package-email]: &lt;email> [; &lt;comment>]</pre>

  <p>The package email address. If not specified, then assumed to be the same
  as <code>email</code>. It only makes sense to specify this value if the
  project and package are maintained separately.</p>

  <h3 id="manifest-package-build-email">6.2.18 <code>build-email</code></h3>

  <pre>[build-email]: &lt;email> [; &lt;comment>]</pre>

  <p>The build notification email address. It is used to send build result
  notifications by automated build bots. If unspecified, then no build result
  notifications for this package are sent by email.</p>

  <div class="note">
  <p>For backwards compatibility with existing packages, if it is specified
  but empty, then this is the same as unspecified.</p>
  </div>

  <h3 id="manifest-package-warning-email">6.2.19
  <code>build-warning-email</code></h3>

  <pre>[build-warning-email]: &lt;email> [; &lt;comment>]</pre>

  <p>The build warning notification email address. Unlike
  <code>build-email</code>, only build warning and error notifications are
  sent to this email.</p>

  <h3 id="manifest-package-error-email">6.2.20
  <code>build-error-email</code></h3>

  <pre>[build-error-email]: &lt;email> [; &lt;comment>]</pre>

  <p>The build error notification email address. Unlike
  <code>build-email</code>, only build error notifications are sent to this
  email.</p>

  <h3 id="manifest-package-depends">6.2.21 <code>depends</code></h3>

  <pre>[depends]: [*] &lt;alternatives> [; &lt;comment>]</pre>

  <p>Single-line form:</p>

  <pre>&lt;alternatives> = &lt;alternative> [ '|' &lt;alternative>]*
&lt;alternative>  = &lt;dependencies> ['?' &lt;enable-cond>] [&lt;reflect-var>]
&lt;dependencies> = &lt;dependency> | \
    '{' &lt;dependency> [&lt;dependency>]* '}' [&lt;version-constraint>]
&lt;dependency>   = &lt;name> [&lt;version-constraint>]
&lt;enable-cond>  = '(' &lt;buildfile-eval-expr> ')'
&lt;reflect-var>  = &lt;config-var> '=' &lt;value></pre>

  <p>Multi-line form:</p>

  <pre>&lt;alternatives> =
  &lt;alternative>[
  '|'
  &lt;alternative>]*

&lt;alternative>  =
  &lt;dependencies>
  '{'
   [
     'enable' &lt;enable-cond>
   ]

   [
     'require'
     '{'
        &lt;buildfile-fragment>
     '}'

   ] | [

     'prefer'
     '{'
        &lt;buildfile-fragment>
     '}'

     'accept' &lt;accept-cond>
   ]

   [
     'reflect'
     '{'
        &lt;buildfile-fragment>
     '}'
   ]
  '}'

&lt;accept-cond>  = '(' &lt;buildfile-eval-expr> ')'</pre>

  <p>The dependency packages. The most common form of a dependency is a
  package name followed by the optional version constraint. For example:</p>

  <pre>depends: libhello ^1.0.0</pre>

  <p>See <a href="#package-version-constraint">Package Version Constraint</a>
  for the format and semantics of the version constraint. Instead of a
  concrete value, the version in the constraint can also be specified in terms
  of the dependent package's version (that is, its <a
  href="#manifest-package-version"><code>version</code></a> value) using the
  special <code>$</code> value. This mechanism is primarily useful when
  developing related packages that should track each other's versions exactly
  or closely. For example:</p>

  <pre>name: sqlite3
version: 3.18.2
depends: libsqlite3 == $</pre>

  <p>If multiple packages are specified within a single <code>depends</code>
  value, they must be grouped with <code>{}</code>. This can be useful if the
  packages share a version constraint. The group constraint applies to all the
  packages in the group that do not have their own constraint. For
  example:</p>

  <pre>depends: { libboost-any libboost-log libboost-uuid ~1.77.1 } ~1.77.0</pre>

  <p>If the <code>depends</code> value starts with <code>*</code>, then it is
  a <i>build-time</i> dependency. Otherwise it is <i>run-time</i>. For
  example:</p>

  <pre>depends: * byacc >= 20210619</pre>

  <div class="note">
  <p>Most of the build-time dependencies are expected to be tools such as code
  generators, so you can think of <code>*</code> as the executable mark
  printed by <code>ls</code>. An important difference between the two kinds of
  dependencies is that in case of cross-compilation a build-time dependency
  must be built for the host machine, not the target. Build system modules are
  also build-time dependencies.</p>
  </div>

  <p>Two special build-time dependency names are recognized and checked in an
  ad hoc manner: <code>build2</code> (the <code>build2</code> build system)
  and <code>bpkg</code> (the <code>build2</code> package manager). This allows
  us to specify the minimum required build system and package manager
  versions, for example:</p>

  <pre>depends: * build2 >= 0.15.0
depends: * bpkg >= 0.15.0</pre>

  <div class="note">
  <p>If you are developing or packaging a project that uses features from the
  not yet released (staged) version of the <code>build2</code> toolchain, then
  you can use the pre-release version in the constraint. For example:</p>

  <pre>depends: * build2 >= 0.16.0-
depends: * bpkg >= 0.16.0-</pre>
  </div>

  <p>A dependency can be conditional, that is, it is only enabled if a certain
  condition is met. For example:</p>

  <pre>depends: libposix-getopt ^1.0.0 ? ($cxx.target.class == 'windows')</pre>

  <p>The condition after <code>?</code> inside <code>()</code> is a
  <code>buildfile</code> eval context expression that should evaluate to
  <code>true</code> or <code>false</code>, as if it were specified in the
  <code>buildfile</code> <code>if</code> directive (see <a
  href="../../build2/doc/build2-build-system-manual.xhtml#intro-lang-expand">Expansion
  and Quoting</a> and <a
  href="../../build2/doc/build2-build-system-manual.xhtml#intro-if-else">Conditions
  (<code>if-else</code>)</a> for details).</p>

  <p>The condition expression is evaluated after loading the package build
  system skeleton, that is, after loading its <code>root.build</code> (see <a
  href="#package-skeleton">Package Build System Skeleton</a> for details). As
  a result, variable values set by build system modules that are loaded in
  <code>root.build</code> as well as the package's configuration (including
  previously reflected; see below) or computed values can be referenced in
  dependency conditions. For example, given the following
  <code>root.build</code>:</p>

  <pre># root.build

...

using cxx

# MinGW ships POSIX &lt;getopt.h>.
#
need_getopt = ($cxx.target.class == 'windows' &amp;&amp; \
               $cxx.target.system != 'mingw32')

config [bool] config.hello.regex ?= false</pre>

  <p>We could have the following conditional dependencies:</p>

  <pre>depends: libposix-getopt ^1.0.0 ? ($need_getopt) ; Windows &amp;&amp; !MinGW.
depends: libposix-regex  ^1.0.0 ? ($config.hello.regex &amp;&amp; \
                                   $cxx.target.class == 'windows')</pre>

  <p>The first <code>depends</code> value in the above example also shows the
  use of an optional comment. It's a good idea to provide it if the condition
  is not sufficiently self-explanatory.</p>

  <p>A dependency can "reflect" configuration variables to the subsequent
  <code>depends</code> values and to the package configuration. This can be
  used to signal whether a conditional dependency is enabled or which
  dependency alternative was selected (see below). The single-line form of
  <code>depends</code> can only reflect one configuration variable. For
  example:</p>

  <pre>depends: libposix-regex ^1.0.0       \
  ? ($cxx.target.class == 'windows') \
  config.hello.external_regex=true</pre>

  <pre># root.build

...

using cxx

config [bool] config.hello.external_regex ?= false</pre>

  <pre># buildfile

libs =

if $config.hello.external_regex
  import libs += libposix-regex%lib{posix-regex}

exe{hello}: ... $libs</pre>

  <p>In the above example, if the <code>hello</code> package is built for
  Windows, then the dependency on <code>libposix-regex</code> will be enabled
  and the package will be configured with
  <code>config.hello.external_regex=true</code>. This is used in the
  <code>buildfile</code> to decide whether to import
  <code>libposix-regex</code>. While in this example it would have probably
  been easier to just duplicate the check for Windows in the
  <code>buildfile</code> (or, better yet, factor this check to
  <code>root.build</code> and share the result via a computed variable between
  <code>manifest</code> and <code>buildfile</code>), the reflect mechanism is
  the only way to communicate the selected dependency alternative (discussed
  next).</p>

  <div class="note">
  <p>An attempt to set a reflected configuration variable that is overridden
  by the user is an error. In a sense, configuration variables that are used
  to reflect information should be treated as the package's implementation
  details if the package management is involved. If, however, the package is
  configured without <code>bpkg</code>'s involvement, then these variables
  could reasonably be provided as user configuration.</p>

  <p>If you feel the need to allow a reflected configuration variable to also
  potentially be supplied as user configuration, then it's probably a good
  sign that you should turn things around: make the variable only
  user-configurable and use the enable condition instead of reflect.
  Alternatively, you could try to recognize and handle user overrides with the
  help of the <code>$config.origin()</code> function discussed in <a
  href="#dep-config-negotiation">Dependency Configuration Negotiation</a>.</p>
  </div>

  <p>While multiple <code>depends</code> values are used to specify multiple
  packages with the <i>AND</i> semantics, inside <code>depends</code> we can
  specify multiple packages (or groups of packages) with the <i>OR</i>
  semantics, called dependency alternatives. For example:</p>

  <pre>depends: libmysqlclient >= 5.0.3 | libmariadb ^10.2.2</pre>

  <p>When selecting an alternative, <code>bpkg</code> only considers packages
  that are either already present in the build configuration or are selected
  as dependencies by other packages, picking the first alternative with a
  satisfactory version constraint and an acceptable configuration. As a
  result, the order of alternatives expresses a preference. If, however, this
  does not yield a suitable alternative, then <code>bpkg</code> fails asking
  the user to make the selection.</p>

  <p>For example, if the package with the above dependency is called
  <code>libhello</code> and we build it in a configuration that already has
  both <code>libmysqlclient</code> and <code>libmariadb</code>, then
  <code>bpkg</code> will select <code>libmysqlclient</code>, provided the
  existing version satisfies the version constraint. If, however, there are no
  existing packages in the build configuration and we attempt to build just
  <code>libhello</code>, then <code>bpkg</code> will fail asking the user to
  pick one of the alternatives. If we wanted to make <code>bpkg</code> select
  <code>libmariadb</code> we could run:</p>

  <pre>$ bpkg build libhello ?libmariadb</pre>

  <div class="note">
  <p>While <code>bpkg</code>'s refusal to automatically pick an alternative
  that would require building a new package may at first seem unfriendly to
  the user, practical experience shows that such extra user-friendliness would
  rarely justify the potential confusion that it may cause.</p>

  <p>Also note that it's not only the user that can pick a certain alternative
  but also a dependent package. Continuing with the above example, if we had
  <code>hello</code> that depended on <code>libhello</code> but only supported
  MariaDB (or provided a configuration variable to explicitly select the
  database), then we could have the following in its
  <code>manifest</code>:</p>

  <pre>depends: libmariadb       ; Select MariaDB in libhello.
depends: libhello ^1.0.0</pre>
  </div>

  <p>Dependency alternatives can be combined with all the other features
  discussed above: groups, conditional dependencies, and reflect. As mentioned
  earlier, reflect is the only way to communicate the selection to subsequent
  <code>depends</code> values and the package configuration. For example:</p>

  <pre>depends: libmysqlclient >= 5.0.3 config.hello.db='mysql'      | \
         libmariadb ^10.2.2 ? ($cxx.target.class != 'windows')  \
           config.hello.db='mariadb'

depends: libz ^1.2.1100 ? ($config.hello.db == 'mysql')</pre>

  <p>If an alternative is conditional and the condition evaluates to
  <code>false</code>, then this alternative is not considered. If all but one
  alternative are disabled due to conditions, then this becomes an ordinary
  dependency. If all the alternatives are disabled due to conditions, then the
  entire dependency is disabled. For example:</p>

  <pre>depends: libmysqlclient >= 5.0.3 ? ($config.hello.db == 'mysql') | \
         libmariadb ^10.2.2      ? ($config.hello.db == 'mariadb')</pre>

  <p>While there is no need to use the dependency alternatives in the above
  example (since the alternatives are mutually exclusive), it makes for good
  documentation of intent.</p>

  <p>Besides as a single line, the <code>depends</code> value can also be
  specified in a multi-line form which, besides potentially better
  readability, provides additional functionality. In the multi-line form, each
  dependency alternative occupies a separate line and <code>|</code> can be
  specified either at the end of the dependency alternative line or on a
  separate line. For example:</p>

  <pre>depends:
\
libmysqlclient >= 5.0.3 ? ($config.hello.db == 'mysql') |
libmariadb ^10.2.2      ? ($config.hello.db == 'mariadb')
\</pre>

  <p>A dependency alternative can be optionally followed by a block containing
  a number of clauses. The <code>enable</code> clause is the alternative way
  to specify the condition for a conditional dependency while the
  <code>reflect</code> clause is the alternative way to specify the reflected
  configuration variable. The block may also contain <code>#</code>-style
  comments, similar to <code>buildfile</code>. For example:</p>

  <pre>depends:
\
libmysqlclient >= 5.0.3
{
  reflect
  {
    config.hello.db = 'mysql'
  }
}
|
libmariadb ^10.2.2
{
  # TODO: MariaDB support on Windows.
  #
  enable ($cxx.target.class != 'windows')

  reflect
  {
    config.hello.db = 'mariadb'
  }
}
\</pre>

  <p>While the <code>enable</code> clause is essentially the same as its
  inline <code>?</code> variant, the <code>reflect</code> clause is an
  arbitrary <code>buildfile</code> fragment that can have more complex logic
  and assign multiple configuration variables. For example:</p>

  <pre>libmariadb ^10.2.2
{
  reflect
  {
    if ($cxx.target.class == 'windows')
      config.hello.db = 'mariadb-windows'
    else
      config.hello.db = 'mariadb-posix'
  }
}</pre>

  <p>The multi-line form also allows us to express our preferences and
  requirements for the dependency configuration. If all we need is to set one
  or more <code>bool</code> configuration variables to <code>true</code>
  (which usually translates to enabling one or more features), then we can use
  the <code>require</code> clause. For example:</p>

  <pre>libmariadb ^10.2.2
{
  require
  {
    config.libmariadb.cache = true

    if ($cxx.target.class != 'windows')
      config.libmariadb.tls = true
  }
}</pre>

  <p>For more complex dependency configurations instead of
  <code>require</code> we can use the <code>prefer</code> and
  <code>accept</code> clauses. The <code>prefer</code> clause can set
  configuration variables of any type and to any value in order to express the
  package's preferred configuration while the <code>accept</code> condition
  evaluates whether any given configuration is acceptable. If used instead of
  <code>require</code>, both <code>prefer</code> and <code>accept</code> must
  be present. For example:</p>

  <pre>libmariadb ^10.2.2
{
  # We prefer the cache but can work without it.
  # We need the buffer of at least 4KB.
  #
  prefer
  {
    config.libmariadb.cache = true

    config.libmariadb.buffer = ($config.libmariadb.buffer &lt; 4096 \
                                ? 4096                           \
                                : $config.libmariadb.buffer)
  }

  accept ($config.libmariadb.buffer >= 4096)
}</pre>

  <div class="note">
  <p>The <code>require</code> clause is essentially a shortcut for specifying
  the <code>prefer</code>/<code>accept</code> clauses where the
  <code>accept</code> condition simply verifies all the variable values
  assigned in the <code>prefer</code> clause. It is, however, further
  restricted to the common case of only setting <code>bool</code> variables
  and only to <code>true</code> to allow additional optimizations during the
  configuration negotiation.</p>
  </div>

  <p>The <code>require</code> and <code>prefer</code> clauses are arbitrary
  <code>buildfile</code> fragments similar to <code>reflect</code> while the
  <code>accept</code> clause is a <code>buildfile</code> eval context
  expression that should evaluate to <code>true</code> or <code>false</code>,
  similar to <code>enable</code>.</p>

  <p>Given the <code>require</code> and
  <code>prefer</code>/<code>accept</code> clauses of all the dependents of a
  particular dependency, <code>bpkg</code> tries to negotiate a configuration
  acceptable to all of them as described in <a
  href="#dep-config-negotiation">Dependency Configuration Negotiation</a>.</p>

  <p>All the clauses are evaluated in the specified order, that is,
  <code>enable</code>, then <code>require</code> or
  <code>prefer</code>/<code>accept</code>, and finally <code>reflect</code>,
  with the (negotiated, in case of <code>prefer</code>) configuration values
  set by preceding clauses available for examination by the subsequent clauses
  in this <code>depends</code> value as well as in all the subsequent ones.
  For example:</p>

  <pre>depends:
\
libmariadb ^10.2.2
{
  prefer
  {
    config.libmariadb.cache = true

    config.libmariadb.buffer = ($config.libmariadb.buffer &lt; 4096 \
                                ? 4096                           \
                                : $config.libmariadb.buffer)
  }

  accept ($config.libmariadb.buffer >= 4096)

  reflect
  {
    config.hello.buffer = $config.libmariadb.buffer
  }
}
\

depends: liblru ^1.0.0 ? ($config.libmariadb.cache)</pre>

  <p>The above example also highlights the difference between the
  <code>require</code>/<code>prefer</code> and <code>reflect</code> clauses
  that is easy to mix up: in <code>require</code>/<code>prefer</code> we set
  the dependency's while in <code>reflect</code> we set the dependent's
  configuration variables.</p>

  <h3 id="manifest-package-requires">6.2.22 <code>requires</code></h3>

  <pre>[requires]: [*] &lt;alternatives> [; &lt;comment>]

&lt;alternatives> = &lt;alternative> [ '|' &lt;alternative>]*
&lt;alternative>  = &lt;requirements> ['?' [&lt;enable-cond>]] [&lt;reflect-var>]
&lt;requirements> = [&lt;requirement>] | \
    '{' &lt;requirement> [&lt;requirement>]* '}' [&lt;version-constraint>]
&lt;requirement>  = &lt;name> [&lt;version-constraint>]
&lt;enable-cond>  = '(' &lt;buildfile-eval-expr> ')'
&lt;reflect-var>  = &lt;config-var> '=' &lt;value></pre>

  <p>The package requirements other than other packages. Such requirements are
  normally checked in an ad hoc way during package configuration by its
  <code>buildfiles</code> and the primary purpose of capturing them in the
  manifest is for documentation.  However, there are some special requirements
  that are recognized by the tooling (see below). For example:</p>

  <pre>requires: c++11
requires: linux | windows | macos
requires: libc++ ? ($macos) ; libc++ if using Clang on Mac OS.</pre>

  <p>The format of the <code>requires</code> value is similar to <a
  href="#manifest-package-depends"><code>depends</code></a> with the following
  differences. The requirement name (with or without version constraint) can
  mean anything (but must still be a valid package name). Only the
  <code>enable</code> and <code>reflect</code> clauses are permitted. There is
  a simplified syntax with either the requirement or enable condition or both
  being empty and where the comment carries all the information (and is thus
  mandatory). For example:</p>

  <pre>requires: ; X11 libs.
requires: ? ($windows) ; Only 64-bit.
requires: ? ; Only 64-bit if on Windows.
requires: x86_64 ? ; Only if on Windows.</pre>

  <p>Note that <code>requires</code> can also be used to specify dependencies
  on system libraries, that is, the ones not to be packaged. In this case it
  may make sense to also specify the version constraint. For example:</p>

  <pre>requires: libx11 >= 1.7.2</pre>

  <p>To assist potential future automated processing, the following
  pre-defined requirement names should be used for the common
  requirements:</p>

  <pre>c++98
c++03
c++11
c++14
c++17
c++20
c++23</pre>

  <pre>posix
linux
macos
freebsd
openbsd
netbsd
windows</pre>

  <pre>gcc[_X.Y.Z]  ; For example: gcc_6, gcc_4.9, gcc_5.0.0
clang[_X.Y]  ; For example: clang_6, clang_3.4, clang_3.4.1
msvc[_N.U]   ; For example: msvc_14, msvc_15.3</pre>

  <p>The following pre-defined requirement names are recognized by automated
  build bots:</p>

  <pre>bootstrap
host</pre>

  <p>The <code>bootstrap</code> value should be used to mark build system
  modules that require bootstrapping. The <code>host</code> value should be
  used to mark packages, such source code generators, that are normally
  specified as build-time dependencies by other packages and therefore should
  be built in a host configuration. See the <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml"><code>bbot</code>
  documentation</a> for details.</p>

  <h3 id="manifest-package-tests-examples-benchmarks">6.2.23
  <code>tests</code>, <code>examples</code>, <code>benchmarks</code></h3>

  <pre>[tests]: [*] &lt;package> ['?' &lt;enable-cond>] [&lt;reflect-var>]
[examples]: [*] &lt;package> ['?' &lt;enable-cond>] [&lt;reflect-var>]
[benchmarks]: [*] &lt;package> ['?' &lt;enable-cond>] [&lt;reflect-var>]

&lt;package>     = &lt;name> [&lt;version-constraint>]
&lt;enable-cond> = '(' &lt;buildfile-eval-expr> ')'
&lt;reflect-var> = &lt;config-var> '=' &lt;value></pre>

  <p>Separate tests, examples, and benchmarks packages. If the value starts
  with <code>*</code>, then the primary package is a <i>build-time</i>
  dependency for the specified package. Otherwise it is <i>run-time</i>. See
  the <a href="#manifest-package-depends"><code>depends</code></a> value for
  details on <i>build-time</i> dependencies.</p>

  <p>These packages are built and tested by automated build bots together with
  the primary package (see the <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml"><code>bbot</code>
  documentation</a> for details). This, in particular, implies that these
  packages must be available from the primary package's repository or its
  complement repositories, recursively. The recommended naming convention for
  these packages is the primary package name followed by <code>-tests</code>,
  <code>-examples</code>, or <code>-benchmarks</code>, respectively. For
  example:</p>

  <pre>name: hello
tests: hello-tests
examples: hello-examples</pre>

  <p>See <a href="#package-version-constraint">Package Version Constraint</a>
  for the format and semantics of the optional version constraint. Instead of
  a concrete value, it can also be specified in terms of the primary package's
  version (see the <a
  href="#manifest-package-depends"><code>depends</code></a> value for
  details), for example:</p>

  <pre>tests: hello-tests ~$</pre>

  <p>Note that normally the tests, etc., packages themselves (we'll call them
  all test packages for short) do not have an explicit dependency on the
  primary package (in a sense, the primary package has a special test
  dependency on them). They are also not built by automated build bots
  separately from their primary package but may have their own build
  constraints, for example, to be excluded from building on some platforms
  where the primary package is still built, for example:</p>

  <pre>name: hello-tests
builds: -windows</pre>

  <p>Also note that a test package may potentially be used as a test
  dependency for multiple primary packages. In this case a primary package
  normally needs to reflect to the test package the fact that it is the one
  being tested. This can be achieved by setting the test package's
  configuration variable (see the <a
  href="#manifest-package-depends"><code>depends</code></a> value for details
  on reflection). For example:</p>

  <pre>name: hello-foo
tests: hello-tests config.hello_tests.test=hello-foo

name: hello-bar
tests: hello-tests config.hello_tests.test=hello-bar</pre>

  <p>If it is plausible that the test package may also be built explicitly,
  for example, to achieve a more complicated setup (test multiple main
  packages simultaneously, etc), then the test dependencies need to be made
  conditional in the primary packages so that the explicit configuration is
  preferred over the reflections (see the <a
  href="#manifest-package-depends"><code>depends</code></a> value for details
  on conditional dependencies). For example:</p>

  <pre>name: hello-foo
tests: hello-tests \
? (!$defined(config.hello_tests.test)) config.hello_tests.test=hello-foo

name: hello-bar
tests: hello-tests \
? (!$defined(config.hello_tests.test)) config.hello_tests.test=hello-bar</pre>

  <p>Note that in contrast to the <a
  href="#manifest-package-depends"><code>depends</code></a> value, both the
  reflection and condition refer to the variables defined not by the package
  which specifies the test dependency (primary package), but the package such
  a dependency refers to (test package).</p>

  <h3 id="manifest-package-builds">6.2.24 <code>builds</code></h3>

  <pre>[builds]: [&lt;class-uset> ':' ] [&lt;class-expr>] [; &lt;comment>]

&lt;class-uset> = &lt;class-name> [ &lt;class-name>]*
&lt;class-expr> = &lt;class-term> [ &lt;class-term>]*
&lt;class-term> = ('+'|'-'|'&amp;')['!'](&lt;class-name> | '(' &lt;class-expr> ')')</pre>

  <p>The common package build target configurations. They specify the target
  configuration classes the package should or should not be built for by
  automated build bots, unless overridden by a package configuration-specific
  value (see <a
  href="#manifest-package-build-config"><code>*-build-config</code></a> for
  details). For example:</p>

  <pre>builds: -windows</pre>

  <p>Build target configurations can belong to multiple classes with their
  names and semantics varying between different build bot deployments.
  However, the pre-defined <code>none</code>, <code>default</code>,
  <code>all</code>, <code>host</code>, and <code>build2</code> classes are
  always provided. If no <code>builds</code> value is specified in the package
  manifest, then the <code>default</code> class is assumed.</p>

  <div class="note">
  <p>A target configuration class can also derive from another class in which
  case configurations that belong to the derived class are treated as also
  belonging to the base class (or classes, recursively). See the Build
  Configurations page of the build bot deployment for the list of available
  target configurations and their classes.</p>
  </div>

  <p>The <code>builds</code> value consists of an optional underlying class
  set (<code>&lt;class-uset></code>) followed by a class set expression
  (<code>&lt;class-expr></code>). The underlying set is a space-separated list
  of class names that define the set of build target configurations to
  consider. If not specified, then all the configurations belonging to the
  <code>default</code> class are assumed. The class set expression can then be
  used to exclude certain configurations from this initial set.</p>

  <p>The class expression is a space-separated list of terms that are
  evaluated from left to right. The first character of each term determines
  whether the build target configuration that belong to its set are added to
  (<code>+</code>), subtracted from (<code>-</code>), or intersected with
  (<code>&amp;</code>) the current set. If the second character in the term is
  <code>!</code>, then its set of configuration is inverted against the
  underlying set. The term itself can be either the class name or a
  parenthesized expression. Some examples (based on the <a
  href="https://ci.cppget.org/?build-configs">cppget.org</a> deployment):</p>

  <pre>builds: none                          ; None.
builds: all                           ; All (suitable for libraries).
builds: all : &amp;host                   ; All host (suitable for tools).
builds: default                       ; All default.
builds: default : &amp;host               ; Default host.
builds: default legacy                ; All default and legacy.
builds: default legacy : &amp;host        ; Default and legacy host.
builds: -windows                      ; Default except Windows.
builds: all : -windows                ; All except Windows.
builds: all : -mobile                 ; All except mobile.
builds: all : &amp;gcc                    ; All with GCC only.
builds: all : &amp;gcc-8+                 ; All with GCC 8 and up only.
builds: all : &amp;gcc -optimized         ; All GCC without optimization.
builds: all : &amp;gcc &amp;( +linux +macos ) ; All GCC on Linux and Mac OS.</pre>

  <p>Notice that the colon and parentheses must be separated with spaces from
  both preceding and following terms.</p>

  <p>Multiple <code>builds</code> values are evaluated in the order specified
  and as if they were all part of a single expression. Only the first value
  may specify the underlying set. The main reason for having multiple values
  is to provide individual reasons (as the <code>builds</code> value comments)
  for different parts of the expression. For example:</p>

  <pre>builds: default experimental ; Only modern compilers are supported.
builds: -gcc                 ; GCC is not supported.
builds: -clang               ; Clang is not supported.</pre>

  <pre>builds: default
builds: -( +macos &amp;gcc)      ; Homebrew GCC is not supported.</pre>

  <div class="note">
  <p>The <code>builds</code> value comments are used by the web interface
  (<code>brep</code>) to display the reason for the build target configuration
  exclusion.</p>
  </div>

  <p>After evaluating all the <code>builds</code> values, the final
  configuration set can be further fine-tuned using the <a
  href="#manifest-package-include-exclude"><code>build-{include,
  exclude}</code></a> patterns.</p>

  <h3 id="manifest-package-include-exclude">6.2.25 <code>build-{include,
  exclude}</code></h3>

  <pre>[build-include]: &lt;config>[/&lt;target>] [; &lt;comment>]
[build-exclude]: &lt;config>[/&lt;target>] [; &lt;comment>]</pre>

  <p>The common package build inclusions and exclusions. The
  <code>build-include</code> and <code>build-exclude</code> values further
  reduce the configuration set produced by evaluating the <a
  href="#manifest-package-builds"><code>builds</code></a> values. The
  <i>config</i> and <i>target</i> values are filesystem wildcard patterns
  which are matched against the build target configuration names and target
  names (see the <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml"><code>bbot</code>
  documentation</a> for details). In particular, the <code>*</code> wildcard
  matches zero or more characters within the name component while the
  <code>**</code> sequence matches across the components. Plus, wildcard-only
  pattern components match absent name components. For example:</p>

  <pre>build-exclude: windows**    # matches windows_10-msvc_15
build-exclude: macos*-gcc** # matches macos_10.13-gcc_8.1-O3
build-exclude: linux-gcc*-* # matches linux-gcc_8.1 and linux-gcc_8.1-O3</pre>

  <p>The exclusion and inclusion patterns are applied in the order specified
  with the first match determining whether the package will be built for this
  configuration and target. If none of the patterns match (or none we
  specified), then the package is built.</p>

  <p>As an example, the following value will exclude 32-bit builds for the
  MSVC 14 compiler:</p>

  <pre>build-exclude: *-msvc_14**/i?86-** ; Linker crash.</pre>

  <p>As another example, the following pair of values will make sure that a
  package is only built on Linux:</p>

  <pre>build-include: linux**
build-exclude: ** ; Only supported on Linux.</pre>

  <p>Note that the comment of the matching exclusion is used by the web
  interface (<code>brep</code>) to display the reason for the build target
  configuration exclusion.</p>

  <h3 id="manifest-package-build-auxiliary">6.2.26
  <code>build-auxiliary</code></h3>

  <pre>[build-auxiliary]: &lt;config> [; &lt;comment>]
[build-auxiliary-&lt;name>]: &lt;config> [; &lt;comment>]</pre>

  <p>The common package build auxiliary configurations. The
  <code>build-auxiliary</code> values can be used to specify auxiliary
  configurations that provide additional components which are required for
  building or testing a package and that are impossible or impractical to
  provide as part of the build configuration itself. For example, a package
  may need access to a suitably configured database, such as PostgreSQL, in
  order to run its tests. Currently no more than <code>9</code> auxiliary
  configurations can be specified.</p>

  <p>The <i>config</i> value is a filesystem wildcard patterns which is
  matched against the auxiliary configuration names (which are in turn derived
  from auxiliary machine names; see the <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml"><code>bbot</code>
  documentation</a> for details). In particular, the <code>*</code> wildcard
  matches zero or more characters within the name component while the
  <code>**</code> sequence matches across the components. Plus, wildcard-only
  pattern components match absent name components. For example:</p>

  <pre>build-auxiliary: linux_debian_12-postgresql_16
build-auxiliary: linux_*-postgresql_*
build-auxiliary: *-postgresql**</pre>

  <div class="note">
  <p>If multiple auxiliary configurations match the specified pattern, then
  one is picked at random for every build.</p>
  </div>

  <p>If multiple auxiliary configurations are required, then they must be
  given distinct names with the <i>name</i> component. For example:</p>

  <pre>build-auxiliary-pgsql: *-postgresql_*
build-auxiliary-mysql: *-mysql_*</pre>

  <p>Another example:</p>

  <pre>build-auxiliary-primary: *-postgresql_*
build-auxiliary-secondary: *-postgresql_*</pre>

  <p>Auxiliary machines communicate information about their setup to the build
  machine using environment variables (see <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml#arch-task-auxiliary-environment"><code>auxiliary-environment</code></a>
  for details). For example, an auxiliary machine that provides a test
  PostgreSQL database may need to communicate the host IP address and port on
  which it can be accessed as well as the user to login as and the database
  name to use. For example:</p>

  <pre>DATABASE_HOST=192.168.0.1
DATABASE_PORT=5432
DATABASE_USER=test
DATABASE_NAME=test</pre>

  <p>If the auxiliary configuration is specified as
  <code>build-auxiliary-&lt;name></code>, then capitalized and sanitized
  <i>name</i>_ is used as a prefix in the environment variables corresponding
  to the machine. For example, for the auxiliary configurations specified
  as:</p>

  <pre>build-auxiliary-pg-sql: *-postgresql_*
build-auxiliary-my-sql: *-mysql_*</pre>

  <p>The environment variables could be:</p>

  <pre>PG_SQL_DATABASE_HOST=192.168.0.1
PG_SQL_DATABASE_PORT=5432
...

MY_SQL_DATABASE_HOST=192.168.0.2
MY_SQL_DATABASE_PORT=3306
...</pre>

  <p>The auxiliary environment variables are in effect for the entire build.
  The recommended place to propagate them to the package configuration is the
  <code>*-build-config</code> value. For example:</p>

  <pre>build-auxiliary: *-postgresql_*
default-build-config:
\
config.hello.pgsql_host=$getenv(DATABASE_HOST)
config.hello.pgsql_port=$getenv(DATABASE_PORT)
...
\</pre>

  <h3 id="manifest-package-build-bot">6.2.27 <code>build-bot</code></h3>

  <pre>[build-bot]: &lt;pub-key></pre>

  <p>The common package build custom bot public key (see <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml"><code>build2</code>
  build bot manual</a> for background). Multiple <code>build-bot</code> values
  can be specified to list several custom build bots. If specified, then such
  custom bots will be used instead of (note: not in addition to) the default
  bots to build this package. Custom bots can be used, for example, to
  accommodate packages that have special requirements, such as proprietary
  dependencies, and which cannot be fulfilled using the default bots. The
  public key should be in the PEM format. For example:</p>

  <pre>build-bot:
\
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAw5liP5pyU9ebC/nD3djZ
1H2dlKmUyiX0Z8POvKhLREd0B3rM59bPcnbRB4HMIhj0J0hUBvS8xb4u5udCPToa
x0A/LMWZ6claiivNtJ3CdLV98eklWdNUg5WXOuqq9QDKXw2ZpGbwDwCOh6aHSWVq
98N9AQx0ZMmMWz3qhRyxPfh+GeJ05uj2ohU9FeUJxeqUcgJT/UcMZ3+7KYbwr+Uq
/HCoX1BmN6nvzhQGHvJIZ2IcjvOQ0AUrPmpSZN01Zr3ZEpkHM3hJWNLu3ntJLGBQ
0aT5kG3iqFyr9q3M3c4J8c0AWrnDjvj0qnCyjNwqW+qIpatmCNT43DmgYr9fQLW0
UHusburz53AbXs12zu3gZzkb0irlShatkMqqQaqaU0/+zw1LnoZ+rvmn2XV97UuK
LFKMKXCnyi2ZG65IZHGkjBVAPuvsX6RgLNyner/QtkDJTbfhktInbG08dCPqv1EF
1OtcYKMTn8I5P2VmMO6SXXDLMSdU8b5DA5EY6Ca6JBB8g06S9sqGqXgQFysAnZs1
VFgMopf8WZqj23x+DX+9KKT2pVnjbwRvBAntuCDoO75gWoETDnCQXEei/PbyamPq
9+NjNsTDn67iJTGncZbII+eciY2YiFHm6GMzBPsUYlQcxiuO4X36jW6m2rwuw37K
oFDbGI3uY4LnhwmDFLbjtk8CAwEAAQ==
-----END PUBLIC KEY-----
\</pre>

  <p>Note that such custom build bots must offer the same set of machines (or
  a subset thereof) as the default bots. In other words, you cannot invent new
  build configuration names (and the corresponding machines) with custom build
  bots &#8211; for that you would need to run your own <code>brep</code>
  deployment. Note also that the list of machines offered by custom bots
  should be consistent with the build configurations enabled by the package
  (see <a href="#manifest-package-builds"><code>builds</code></a> for
  details). For example, if the package enables a configuration that is not
  offered by any of the custom bots listed, then this configuration will
  remain unbuilt forever.</p>

  <div class="note">
  <p>Note that custom build bot public keys are publicly known and nothing
  prevents someone else from specifying your bot's public key in their own
  package and thus triggering a build on your bot of a potentially rogue
  package. As a result, carefully consider the information that you make
  available in your custom machines (which will be easy to exfiltrate) as well
  as the environment in which you run your custom bots (which can potentially
  be compromised). In the future, <code>bbot</code> may offer mechanisms to
  restrict the names and locations of packages that it is allowed to
  build.</p>
  </div>

  <h3 id="manifest-package-build-config">6.2.28
  <code>*-build-config</code></h3>

  <pre>[*-build-config]: &lt;args> [; &lt;comment>]

&lt;args> = [[[+|-]&lt;prefix>:](&lt;option>|&lt;config-var>)]* \
         [(+|-)&lt;prefix>:]*                          \
         [&lt;dependency-spec>]*                       \
         [&lt;package-specific-vars>]*

&lt;dependency-spec> = [{ &lt;config-var> [&lt;config-var>]* }+] &lt;dependency>
&lt;dependency> = (?[sys:]|sys:)&lt;name>[&lt;version-spec>]
&lt;version-spec> = /&lt;version> | &lt;version-constraint>
&lt;package-specific-vars> = { &lt;config-var> [&lt;config-var>]* }+ &lt;name>

[*-builds]: &lt;class-expr> [; &lt;comment>]
[*-build-include]: &lt;config>[/&lt;target>] [; &lt;comment>]
[*-build-exclude]: &lt;config>[/&lt;target>] [; &lt;comment>]
[*-build-auxiliary]: &lt;config> [; &lt;comment>]
[*-build-auxiliary-&lt;name>]: &lt;config> [; &lt;comment>]
[*-build-bot]: &lt;pub-key>

[*-build-email]: &lt;email> [; &lt;comment>]
[*-build-warning-email]: &lt;email> [; &lt;comment>]
[*-build-error-email]: &lt;email> [; &lt;comment>]</pre>

  <p>The package build configurations where the substring matched by
  <code>*</code> in <code>*-build-config</code> denotes the configuration
  name. If specified, then the package is built in these configurations by
  automated build bots in addition to the default configuration (which is
  called <code>default</code>).</p>

  <p>The <code>*-build-config</code> values contain whitespace separated lists
  of potentially double/single-quoted package configuration arguments. The
  global (as opposed to package-specific) options and variables can be
  prefixed with the build bot worker script step ids or a leading portion
  thereof to restrict it to a specific step, operation, phase, or tool (see <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml#arch-worker"><code><b>bbot</b></code>
  worker step ids</a>). The prefix can optionally begin with the
  <code>+</code> or <code>-</code> character (in this case the argument can be
  omitted) to enable or disable the respective step (see the list of <a
  href="../../bbot/doc/build2-build-bot-manual.xhtml#arch-controller">worker
  steps</a> which can be enabled or disabled). Unprefixed global options,
  variables, and dependencies are passed to the <a
  href="bpkg-pkg-build.xhtml"><code><b>bpkg-pkg-build(1)</b></code></a>
  command at the <code>bpkg.configure.build</code> step. The package-specific
  configuration variables for this and/or the separate test packages are
  passed to <a
  href="bpkg-pkg-build.xhtml"><code><b>bpkg-pkg-build(1)</b></code></a> at the
  <code>bpkg.configure.build</code> and
  <code>bpkg.test-separate-installed.configure.build</code> steps. For
  example:</p>

  <pre>network-build-config: config.libfoo.network=true; Enable networking API.

cache-build-config:
\
config.libfoo.cache=true
config.libfoo.buffer=4096
;
Enable caching.
\

libbar-network-build-config:
\
{ config.libbar.network=true }+ ?libbar
;
Enable networking API in libbar.
\

older-libz-build-config: "?libz ^1.0.0"; Test with older libz version.

sys-build-config:
\
?sys:libbar ?sys:libz
;
Test with system dependencies.
\

bindist-build-config:
\
+bpkg.bindist.debian:--recursive=full
-bbot.sys-install:
+bbot.bindist.upload:
;
Generate and upload binary distribution package but don't test its installation.
\

load-tests-build-config:
\
{ config.libfoo_tests.load=true }+ libfoo-tests
;
Enable load testing.
\</pre>

  <p>Note that options with values can only be specified using the single
  argument notation, for example, <code>--verbose=4</code>.</p>

  <p>The package build configuration can override the common build target
  configurations set (specified with <a
  href="#manifest-package-builds"><code>builds</code></a> and <a
  href="#manifest-package-include-exclude"><code>build-{include,
  exclude}</code></a>) by specifying the matching <code>*-builds</code> and/or
  <code>*-build-{include, exclude}</code> values. For example:</p>

  <pre>network-builds: linux; Only supported on Linux.
network-build-config: config.libfoo.network=true; Enable networking API.</pre>

  <p>Note that the common build target configurations set is overridden
  hierarchically meaning that the <code>*-build-{include, exclude}</code>
  overrides don't discard the common <code>builds</code> values.</p>

  <p>The package build configuration can override the common build auxiliary
  machines. Note that the auxiliary machine set is overridden entirely,
  meaning that specifying one <code>*-build-auxiliary</code> value discard all
  the common <code>build-auxiliary</code> values for this package
  configuration.</p>

  <p>The package build configuration can override the common build custom
  bots. Note that the custom bot set is overridden entirely, meaning that
  specifying one <code>*-build-bot</code> value discards all the common
  <code>build-bot</code> values for this package configuration.</p>

  <p>The package build configuration can override the common build
  notification email addresses (specified with <a
  href="#manifest-package-build-email"><code>build-email</code></a>, <a
  href="#manifest-package-warning-email"><code>build-warning-email</code></a>,
  and <a
  href="#manifest-package-error-email"><code>build-error-email</code></a>) by
  specifying the matching <code>*-build-email</code> and/or
  <code>*-build-{warning, error}-email</code> values. For example:</p>

  <pre>bindist-build-config:
\
+bpkg.bindist.debian:--recursive=full
+bbot.bindist.upload:
;
Generate and upload binary distribution package.
\
bindist-build-error-email: builds@example.org</pre>

  <p>Note that to disable all the build notification emails for a specific
  package build configuration, specify the empty <code>*-build-email</code>
  value. For example:</p>

  <pre>sys-build-config: ?sys:libz; Test with system dependencies.
sys-build-email:</pre>

  <p>The default configuration should normally build the package with no
  configuration arguments and for the common target build configurations set.
  While not recommended, this can be overridden by using the special
  <code>default</code> configuration name. For example:</p>

  <pre>default-build-config: config.libfoo.cache=true</pre>

  <h3 id="manifest-package-build-file">6.2.29 <code>build-file</code></h3>

  <pre>[build-file]: &lt;path>

[bootstrap-build]: &lt;text>
[root-build]: &lt;text>
[*-build]: &lt;text>

[bootstrap-build2]: &lt;text>
[root-build2]: &lt;text>
[*-build2]: &lt;text></pre>

  <p>The contents of the mandatory <code>bootstrap.build</code> file, optional
  <code>root.build</code> file, and additional files included by
  <code>root.build</code>, or their alternative naming scheme variants
  (<code>bootstrap.build2</code>, etc). Packages with the alternative naming
  scheme should use the <code>*-build2</code> values instead of
  <code>*-build</code>. See <a href="#package-skeleton">Package Build System
  Skeleton</a> for background.</p>

  <p>These files must reside in the package's <code>build/</code> subdirectory
  and have the <code>.build</code> extension (or their alternative names).
  They can be provided either inline as text fragments or, for additional
  files, by referring to them with a path relative to this subdirectory, but
  not both. The <code>*-build</code>/<code>*-build2</code> manifest value name
  prefixes must be the file paths relative to this subdirectory with the
  extension stripped.</p>

  <p>As an example, the following values correspond to the
  <code>build/config/common.build</code> file:</p>

  <pre>build-file: config/common.build

config/common-build:
\
config [bool] config.libhello.fancy ?= false
\</pre>

  <p>And the following values correspond to the
  <code>build2/config/common.build2</code> file in a package with the
  alternative naming scheme:</p>

  <pre>build-file: config/common.build2

config/common-build2:
\
config [bool] config.libhello.fancy ?= false
\</pre>

  <p>If unspecified, then the package's <code>bootstrap.build</code>,
  <code>root.build</code>, and <code>build/config/*.build</code> files (or
  their alternative names) will be automatically added, for example, when the
  <a href="#manifest-package-list-pkg">package list manifest</a> is
  created.</p>

  <h3 id="manifest-package-distribution">6.2.30 <code>*-{name, version,
  to-downstream-version}</code></h3>

  <pre>[&lt;distribution>-name]: &lt;name> [&lt;name>...]
[&lt;distribution>-version]: &lt;string>
[&lt;distribution>-to-downstream-version]: &lt;regex>

&lt;distribution> = &lt;name>[_&lt;version>]
&lt;regex> = /&lt;pattern>/&lt;replacement>/</pre>

  <p>The binary distribution package name and version mapping. The
  <code>-name</code> value specifies the distribution package(s) this
  <code>bpkg</code> package maps to. If unspecified, then appropriate name(s)
  are automatically derived from the <code>bpkg</code> package name (<a
  href="#manifest-package-name"><code>name</code></a>). Similarly, the
  <code>-version</code> value specifies the distribution package version. If
  unspecified, then the <code>upstream-version</code> value is used if
  specified and the <code>bpkg</code> version (<a
  href="#manifest-package-version"><code>version</code></a>) otherwise. While
  the <code>-to-downstream-version</code> values specify the reverse mapping,
  that is, from the distribution version to the <code>bpkg</code> version. If
  unspecified or none match, then the appropriate part of the distribution
  version is used. For example:</p>

  <pre>name: libssl
version 1.1.1+18
debian-name: libssl1.1 libssl-dev
debian-version: 1.1.1n
debian-to-downstream-version: /1\.1\.1[a-z]/1.1.1/
debian-to-downstream-version: /([3-9])\.([0-9]+)\.([0-9]+)/\1.\2.\3/</pre>

  <p>If <code>upstream-version</code> is specified but the the distribution
  package version should be the same as the <code>bpkg</code> package version,
  then the special <code>$</code> <code>-version</code> value can be used. For
  example:</p>

  <pre>debian-version: $</pre>

  <p>The <code>&lt;distribution></code> name prefix consists of the
  distribution name followed by the optional distribution version. If the
  version is omitted, then the value applies to all versions. Some examples of
  distribution names and versions:</p>

  <pre>debian
debian_10
ubuntu_16.04
fedora_32
rhel_8.5
freebsd_12.1
windows_10
macos_10
macos_10.15
macos_12</pre>

  <p>Note also that some distributions are like others (for example,
  <code>ubuntu</code> is like <code>debian</code>) and the corresponding
  "base" distribution values are considered if no "derived" values are
  specified.</p>

  <p>The <code>-name</code> value is used both during package consumption as a
  system package and production with the <a
  href="bpkg-pkg-bindist.xhtml"><code><b>bpkg-pkg-bindist(1)</b></code></a>
  command. During production, if multiple mappings match, then the value with
  the highest matching distribution version from the package
  <code>manifest</code> with the latest version is used. If it's necessary to
  use different names for the generated binary packages (called "non-native
  packages" in contrast to "native packages" that come from the distribution),
  the special <code>0</code> distribution version can be used to specify such
  a mapping. For example:</p>

  <pre>name: libsqlite3
debian_9-name: libsqlite3-0 libsqlite3-dev
debian_0-name: libsqlite3 libsqlite3-dev</pre>

  <p>Note that this special non-native mapping is ignored during consumption
  and a deviation in the package names that it introduces may make it
  impossible to use native and non-native binary packages interchangeably, for
  example, to satisfy dependencies.</p>

  <p>The exact format of the <code>-name</code> and <code>-version</code>
  values and the distribution version part that is matched against the
  <code>-to-downstream-version</code> pattern are distribution-specific. For
  details, see <a href="#bindist-mapping-debian">Debian Package Mapping</a>
  and <a href="#bindist-mapping-fedora">Fedora Package Mapping</a>.</p>

  <h2 id="manifest-package-list-pkg">6.3 Package List Manifest for
  <code><b>pkg</b></code> Repositories</h2>

  <p>The package list manifest (the <code>packages.manifest</code> file found
  in the <code><b>pkg</b></code> repository root directory) describes the list
  of packages available in the repository. First comes a manifest that
  describes the list itself (referred to as the list manifest). The list
  manifest synopsis is presented next:</p>

  <pre>sha256sum: &lt;sum></pre>

  <p>After the list manifest comes a (potentially empty) sequence of package
  manifests. These manifests shall not contain any <code>*-file</code> or
  incomplete <a href="#manifest-package-depends"><code>depends</code></a>
  values (such values should be converted to their inline versions or
  completed, respectively) but must contain the <code>*-build</code> values
  (unless the corresponding files are absent) and the following additional (to
  package manifest) values:</p>

  <pre>location: &lt;path>
sha256sum: &lt;sum></pre>

  <p>The detailed description of each value follows in the subsequent
  sections.</p>

  <h3 id="manifest-package-list-pkg-sha256sum">6.3.1 <code>sha256sum</code>
  (list manifest)</h3>

  <pre>sha256sum: &lt;sum></pre>

  <p>The SHA256 checksum of the <code>repositories.manifest</code> file
  (described below) that corresponds to this repository. The <i>sum</i> value
  should be 64 characters long (that is, just the SHA256 value, no file name
  or any other markers), be calculated in the binary mode, and use lower-case
  letters.</p>

  <div class="note">
  <p>This checksum is used to make sure that the
  <code>repositories.manifest</code> file that was fetched is the same as the
  one that was used to create the <code>packages.manifest</code> file. This
  also means that if <code>repositories.manifest</code> is modified in any
  way, then <code>packages.manifest</code> must be regenerated as well.</p>
  </div>

  <h3 id="manifest-package-list-pkg-package-location">6.3.2
  <code>location</code> (package manifest)</h3>

  <pre>location: &lt;path></pre>

  <p>The path to the package archive file relative to the repository root. It
  should be in the POSIX representation.</p>

  <div class="note">
  <p>if the repository keeps multiple versions of the package and places them
  all into the repository root directory, it can get untidy. With
  <code>location</code> we allow for sub-directories.</p>
  </div>

  <h3 id="manifest-package-list-pkg-package-sha256sum">6.3.3
  <code>sha256sum</code> (package manifest)</h3>

  <pre>sha256sum: &lt;sum></pre>

  <p>The SHA256 checksum of the package archive file. The <i>sum</i> value
  should be 64 characters long (that is, just the SHA256 value, no file name
  or any other markers), be calculated in the binary mode, and use lower-case
  letters.</p>

  <h2 id="manifest-package-list-dir">6.4 Package List Manifest for
  <code><b>dir</b></code> Repositories</h2>

  <p>The package list manifest (the <code>packages.manifest</code> file found
  in the <code><b>dir</b></code> repository root directory) describes the list
  of packages available in the repository. It is a (potentially empty)
  sequence of manifests with the following synopsis:</p>

  <pre>location: &lt;path>
[fragment]: &lt;string></pre>

  <p>The detailed description of each value follows in the subsequent
  sections. The <code>fragment</code> value can only be present in a merged
  <code>packages.manifest</code> file for a multi-fragment repository.</p>

  <p>As an example, if our repository contained the <code>src/</code>
  subdirectory that in turn contained the <code>libfoo</code> and
  <code>foo</code> packages, then the corresponding
  <code>packages.manifest</code> file could look like this:</p>

  <pre>: 1
location: src/libfoo/
:
location: src/foo/</pre>

  <h3 id="manifest-package-list-dir-location">6.4.1 <code>location</code></h3>

  <pre>location: &lt;path></pre>

  <p>The path to the package directory relative to the repository root. It
  should be in the POSIX representation.</p>

  <h3 id="manifest-package-list-dir-fragment">6.4.2 <code>fragment</code></h3>

  <pre>[fragment]: &lt;string></pre>

  <p>The repository fragment id this package belongs to.</p>

  <h2 id="manifest-repository">6.5 Repository Manifest</h2>

  <p>The repository manifest (only used as part of the repository manifest
  list described below) describes a <code><b>pkg</b></code>,
  <code><b>dir</b></code>, or <code><b>git</b></code> repository. The manifest
  synopsis is presented next followed by the detailed description of each
  value in subsequent sections.</p>

  <pre>[location]: &lt;uri>
[type]: pkg|dir|git
[role]: base|prerequisite|complement
[trust]: &lt;fingerprint>
[url]: &lt;url>
[email]: &lt;email> [; &lt;comment>]
[summary]: &lt;text>
[description]: &lt;text>
[certificate]: &lt;pem>
[fragment]: &lt;string></pre>

  <p>See also the Repository Chaining documentation for further information @@
  TODO.</p>

  <h3 id="manifest-repository-location">6.5.1 <code>location</code></h3>

  <pre>[location]: &lt;uri></pre>

  <p>The repository location. The location can and must only be omitted for
  the base repository. <span class="note">Since we got hold of its manifest,
  then we presumably already know the location of the base repository.</span>
  If the location is a relative path, then it is treated as relative to the
  base repository location.</p>

  <p>For the <code><b>git</b></code> repository type the relative location
  does not inherit the URL fragment from the base repository. Note also that
  the remote <code><b>git</b></code> repository locations normally have the
  <code><b>.git</b></code> extension that is stripped when a repository is
  cloned locally. To make the relative locations usable in both contexts, the
  <code><b>.git</b></code> extension should be ignored if the local
  prerequisite repository with the extension does not exist while the one
  without the extension does.</p>

  <p>While POSIX systems normally only support POSIX paths (that is, forward
  slashes only), Windows is generally able to handle both slash types. As a
  result, it is recommended that POSIX paths are always used in the
  <code>location</code> values, except, perhaps, if the repository is
  explicitly Windows-only by, for example, having a location that is an
  absolute Windows path with the drive letter. <span class="note">The
  <code><b>bpkg</b></code> package manager will always try to represent the
  location as a POSIX path and only fallback to the native representation if
  that is not possible (for example, there is a drive letter in the
  path).</span></p>

  <h3 id="manifest-repository-type">6.5.2 <code>type</code></h3>

  <pre>[type]: pkg|dir|git</pre>

  <p>The repository type. The type must be omitted for the base repository. If
  the type is omitted for a prerequisite/complement repository, then it is
  guessed from its <code>location</code> value as described in <a
  href="bpkg-rep-add.xhtml"><code><b>bpkg-rep-add(1)</b></code></a>.</p>

  <h3 id="manifest-repository-role">6.5.3 <code>role</code></h3>

  <pre>[role]: base|prerequisite|complement</pre>

  <p>The repository role. The <code>role</code> value can be omitted for the
  base repository only.</p>

  <h3 id="manifest-repository-trust">6.5.4 <code>trust</code></h3>

  <pre>[trust]: &lt;fingerprint></pre>

  <p>The repository fingerprint to trust. The <code>trust</code> value can
  only be specified for prerequisite and complement repositories and only for
  repository types that support authentication (currently only
  <code>pkg</code>). The <i>fingerprint</i> value should be an SHA256
  repository fingerprint represented as 32 colon-separated hex digit pairs.
  <span class="note">The repository in question is only trusted for use as a
  prerequisite or complement of this repository. If it is also used by other
  repositories or is added to the configuration by the user, then such uses
  cases are authenticated independently.</span></p>

  <h3 id="manifest-repository-url">6.5.5 <code>url</code></h3>

  <pre>[url]: &lt;url></pre>

  <p>The repository's web interface (<code>brep</code>) URL. It can only be
  specified for the base repository (the web interface URLs for
  prerequisite/complement repositories can be extracted from their respective
  manifests).</p>

  <p>For example, given the following <code>url</code> value:</p>

  <pre>url: https://example.org/hello/</pre>

  <p>The package details page for <code>libfoo</code> located in this
  repository will be <code>https://example.org/hello/libfoo</code>.</p>

  <p>The web interface URL can also be specified as relative to the repository
  location (the <code>location</code> value). In this case <i>url</i> should
  start with two path components each being either <code>.</code> or
  <code>..</code>. If the first component is <code>..</code>, then the
  <code>www</code>, <code>pkg</code> or <code>bpkg</code> domain component, if
  any, is removed from the <code>location</code> URL host, just like when
  deriving the repository name.</p>

  <p>Similarly, if the second component is <code>..</code>, then the
  <code>pkg</code> or <code>bpkg</code> path component, if any, is removed
  from the <code>location</code> URL path, again, just like when deriving the
  repository name.</p>

  <p>Finally, the version component is removed from the <code>location</code>
  URL path, the rest (after the two <code>.</code>/<code>..</code> components)
  of the <code>url</code> value is appended to it, and the resulting path is
  normalized with all remaining <code>..</code>  and <code>.</code> applied
  normally.</p>

  <p>For example, assuming repository location is:</p>

  <pre>https://pkg.example.org/test/pkg/1/hello/stable</pre>

  <p>The following listing shows some of the possible combinations (the
  <code>&lt;></code> marker is used to highlight the changes):</p>

  <pre>./.          ->  https://pkg.example.org/test/pkg/hello/stable
../.         ->  https://&lt;  >example.org/test/pkg/hello/stable
./..         ->  https://pkg.example.org/test/&lt;  >hello/stable
../..        ->  https://&lt;  >example.org/test/&lt;  >hello/stable
././..       ->  https://pkg.example.org/test/pkg/hello&lt;     >
../../../..  ->  https://&lt;  >example.org/test&lt;               ></pre>

  <div class="note">
  <p>The rationale for the relative web interface URLs is to allow deployment
  of the same repository to slightly different configuration, for example,
  during development, testing, and public use. For instance, for development
  we may use the <code>https://example.org/pkg/</code> setup while in
  production it becomes <code>https://pkg.example.org/</code>. By specifying
  the web interface location as, say, <code>../.</code>, we can run the web
  interface at these respective locations using a single repository
  manifest.</p>
  </div>

  <h3 id="manifest-repository-email">6.5.6 <code>email</code></h3>

  <pre>[email]: &lt;email> [; &lt;comment>]</pre>

  <p>The repository email address. It must and can only be specified for the
  base repository. The email address is displayed by the web interface
  (<code>brep</code>) in the repository about page and could be used to
  contact the maintainers about issues with the repository.</p>

  <h3 id="manifest-repository-summary">6.5.7 <code>summary</code></h3>

  <pre>[summary]: &lt;text></pre>

  <p>The short description of the repository. It must and can only be
  specified for the base repository.</p>

  <h3 id="manifest-repository-description">6.5.8 <code>description</code></h3>

  <pre>[description]: &lt;text></pre>

  <p>The detailed description of the repository. It can only be specified for
  the base repository.</p>

  <p>In the web interface (<code>brep</code>) the description is formatted
  into one or more paragraphs using blank lines as paragraph separators.
  Specifically, it is not represented as <code>&lt;pre></code> so any kind of
  additional plain text formatting (for example, lists) will be lost and
  should not be used in the description.</p>

  <h3 id="manifest-repository-certificate">6.5.9 <code>certificate</code></h3>

  <pre>[certificate]: &lt;pem></pre>

  <p>The X.509 certificate for the repository. It should be in the PEM format
  and can only be specified for the base repository. Currently only used for
  the <code><b>pkg</b></code> repository type.</p>

  <p>The certificate should contain the <code>CN</code> and <code>O</code>
  components in the subject as well as the <code>email:</code> component in
  the subject alternative names. The <code>CN</code> component should start
  with <code>name:</code> and continue with the repository name
  prefix/wildcard (without trailing slash) that will be used to verify the
  repository name(s) that are authenticated with this certificate. See <a
  href="bpkg-repository-signing.xhtml"><code><b>bpkg-repository-signing(1)</b></code></a>
  for details.</p>

  <p>If this value is present then the <code>packages.manifest</code> file
  must be signed with the corresponding private key and the signature saved in
  the <code>signature.manifest</code> file. See <a
  href="#manifest-signature-pkg">Signature Manifest</a> for details.</p>

  <h3 id="manifest-repository-fragment">6.5.10 <code>fragment</code></h3>

  <pre>[fragment]: &lt;string></pre>

  <p>The repository fragment id this repository belongs to.</p>

  <h2 id="manifest-repository-list">6.6 Repository List Manifest</h2>

  <p>@@ TODO See the Repository Chaining document for more information on the
  terminology and semantics.</p>

  <p>The repository list manifest (the <code>repositories.manifest</code> file
  found in the repository root directory) describes the repository. It starts
  with an optional header manifest optionally followed by a sequence of
  repository manifests consisting of the base repository manifest (that is,
  the manifest for the repository that is being described) as well as
  manifests for its prerequisite and complement repositories. The individual
  repository manifests can appear in any order and the base repository
  manifest can be omitted.</p>

  <p>The <code>fragment</code> values can only be present in a merged
  <code>repositories.manifest</code> file for a multi-fragment repository.</p>

  <p>As an example, a repository manifest list for the
  <code>math/testing</code> repository could look like this:</p>

  <pre># math/testing
#
: 1
min-bpkg-version: 0.14.0
:
email: math-pkg@example.org
summary: Math package repository
:
role: complement
location: ../stable
:
role: prerequiste
location: https://pkg.example.org/1/misc/testing</pre>

  <p>Here the first manifest describes the base repository itself, the second
  manifest &#8211; a complement repository, and the third manifest &#8211; a
  prerequisite repository. Note that the complement repository's location is
  specified as a relative path. For example, if the base repository location
  were:</p>

  <pre>https://pkg.example.org/1/math/testing</pre>

  <p>Then the completement's location would be:</p>

  <pre>https://pkg.example.org/1/math/stable</pre>

  <p>The header manifest synopsis is presented next followed by the detailed
  description of each value in subsequent sections.</p>

  <pre>[min-bpkg-version]: &lt;ver>
[compression]: &lt;compressions></pre>

  <h3 id="manifest-repository-list-header-min-bpkg-version">6.6.1
  <code>min-bpkg-version</code></h3>

  <pre>[min-bpkg-version]: &lt;ver></pre>

  <p>The earliest version of <code><b>bpkg</b></code> that is compatible with
  this repository. Note that if specified, it must be the first value in the
  header.</p>

  <h3 id="manifest-repository-list-header-compression">6.6.2
  <code>compression</code></h3>

  <pre>[compression]: &lt;compressions>

&lt;compressions> = &lt;compression> [ &lt;compression>]*</pre>

  <p>Available compressed variants of the <code>packages.manifest</code> file.
  The format is a space-separated list of the compression methods. The
  <code>none</code> method means no compression. Absent
  <code>compression</code> value is equivalent to specifying it with the
  <code>none</code> value.</p>

  <h2 id="manifest-signature-pkg">6.7 Signature Manifest for
  <code><b>pkg</b></code> Repositories</h2>

  <p>The signature manifest (the <code>signature.manifest</code> file found in
  the <code><b>pkg</b></code> repository root directory) contains the
  signature of the repository's <code>packages.manifest</code> file. In order
  to detect the situation where the downloaded <code>signature.manifest</code>
  and <code>packages.manifest</code> files belong to different updates, the
  manifest contains both the checksum and the signature (which is the
  encrypted checksum). <span class="note">We cannot rely on just the signature
  since a mismatch could mean either a split update or tampering.</span> The
  manifest synopsis is presented next followed by the detailed description of
  each value in subsequent sections.</p>

  <pre>sha256sum: &lt;sum>
signature: &lt;sig></pre>

  <h3 id="manifest-signature-pkg-sha256sum">6.7.1 <code>sha256sum</code></h3>

  <pre>sha256sum: &lt;sum></pre>

  <p>The SHA256 checksum of the <code>packages.manifest</code> file. The
  <i>sum</i> value should be 64 characters long (that is, just the SHA256
  value, no file name or any other markers), be calculated in the binary mode,
  and use lower-case letters.</p>

  <h3 id="manifest-signature-pkg-signature">6.7.2 <code>signature</code></h3>

  <pre>signature: &lt;sig></pre>

  <p>The signature of the <code>packages.manifest</code> file. It should be
  calculated by encrypting the above <code>sha256sum</code> value with the
  repository certificate's private key and then <code>base64</code>-encoding
  the result.</p>

  <h1 id="bindist-mapping">7 Binary Distribution Package Mapping</h1>

  <h2 id="bindist-mapping-debian">7.1 Debian Package Mapping</h2>

  <p>This section describes the distribution package mapping for Debian and
  alike (Ubuntu, etc).</p>

  <h3 id="bindist-mapping-debian-consume">7.1.1 Debian Package Mapping for
  Consumption</h3>

  <p>A library in Debian is normally split up into several packages: the
  shared library package (e.g., <code>libfoo1</code> where <code>1</code> is
  the ABI version), the development files package (e.g.,
  <code>libfoo-dev</code>), the documentation files package (e.g.,
  <code>libfoo-doc</code>), the debug symbols package (e.g.,
  <code>libfoo1-dbg</code>), and the architecture-independent files (e.g.,
  <code>libfoo1-common</code>). All the packages except <code>-dev</code> are
  optional and there is quite a bit of variability. Here are a few
  examples:</p>

  <pre>libsqlite3-0 libsqlite3-dev

libssl1.1 libssl-dev libssl-doc
libssl3 libssl-dev libssl-doc

libcurl4 libcurl4-openssl-dev libcurl4-doc
libcurl3-gnutls libcurl4-gnutls-dev libcurl4-doc</pre>

  <p>Note that while most library package names in Debian start with
  <code>lib</code> (per the policy), there are exceptions (e.g.,
  <code>zlib1g</code> <code>zlib1g-dev</code>). The header-only library
  package names may or may not start with <code>lib</code> and end with
  <code>-dev</code> (e.g., <code>libeigen3-dev</code>,
  <code>rapidjson-dev</code>, <code>catch2</code>). Also note that manual
  <code>-dbg</code> packages are obsolete in favor of automatic
  <code>-dbgsym</code> packages from Debian 9.</p>

  <p>For executable packages there is normally no <code>-dev</code> packages
  but <code>-dbg</code>, <code>-doc</code>, and <code>-common</code> are
  plausible.</p>

  <p>Based on that, our approach when trying to automatically map a
  <code>bpkg</code> library package name to Debian package names is to go for
  the <code>-dev</code> package first and figure out the shared library
  package from that based on the fact that the <code>-dev</code> package
  should have the <code>==</code> dependency on the shared library package
  with the same version and its name should normally start with the
  <code>-dev</code> package's stem.</p>

  <p>The format of the <code>debian-name</code> (or alike) manifest value is a
  comma-separated list of one or more package groups:</p>

  <pre>&lt;package-group> [, &lt;package-group>...]</pre>

  <p>Where each <code>&lt;package-group></code> is the space-separated list of
  one or more package names:</p>

  <pre>&lt;package-name> [ &lt;package-name>...]</pre>

  <p>All the packages in the group should be "package components" (for the
  lack of a better term) of the same "logical package", such as
  <code>-dev</code>, <code>-doc</code>, <code>-common</code> packages. They
  normally have the same version.</p>

  <p>The first group is called the main group and the first package in the
  group is called the main package. Note that all the groups are consumed
  (installed) but only the main group is produced (packaged).</p>

  <p>We allow/recommend specifying the <code>-dev</code> package instead of
  the main package for libraries (see <a
  href="#manifest-package-type-language"><code>type</code></a> for details),
  seeing that we are capable of detecting the main package automatically (see
  above). If the library name happens to end with <code>-dev</code> (which
  poses an ambiguity), then the <code>-dev</code> package should be specified
  explicitly as the second package to disambiguate this situation.</p>

  <p>The Debian package version has the
  <code>[&lt;epoch>:]&lt;upstream>[-&lt;revision>]</code> form (see
  <code><b>deb-version(5)</b></code> for details). If no explicit mapping to
  the <code>bpkg</code> version is specified with the
  <code>debian-to-downstream-version</code> (or alike) manifest values or none
  match, then we fallback to using the <code>&lt;upstream></code> part as the
  <code>bpkg</code> version. If explicit mapping is specified, then we match
  it against the <code>[&lt;epoch>:]&lt;upstream></code> parts ignoring
  <code>&lt;revision></code>.</p>

  <h3 id="bindist-mapping-debian-produce">7.1.2 Debian Package Mapping for
  Production</h3>

  <p>The same <code>debian-name</code> (or alike) manifest values as used for
  consumption are also used to derive the package names for production except
  here we have the option to specify alternative non-native package names
  using the special <code>debian_0-name</code> (or alike) value. If only the
  <code>-dev</code> package is specified, then the main package name is
  derived from that by removing the <code>-dev</code> suffix. Note that
  regardless of whether the main package name is specified or not, the <a
  href="bpkg-pkg-bindist.xhtml"><code><b>bpkg-pkg-bindist(1)</b></code></a>
  command may omit generating the main package for a binless library.</p>

  <p>The generated binary package version can be specified with the
  <code>debian-version</code> (or alike) manifest value. If it's not
  specified, then the <code>upstream-version</code> is used if specified.
  Otherwise, the <code>bpkg</code> version is translated to the Debian version
  as described next.</p>

  <p>To recap, a Debian package version has the following form:</p>

  <pre>[&lt;epoch>:]&lt;upstream>[-&lt;revision>]</pre>

  <p>For details on the ordering semantics, see the <code>Version</code>
  <code>control</code> file field documentation in the Debian Policy Manual.
  While overall unsurprising, one notable exception is <code>~</code>, which
  sorts before anything else and is commonly used for upstream pre-releases.
  For example, <code>1.0~beta1~svn1245</code> sorts earlier than
  <code>1.0~beta1</code>, which sorts earlier than <code>1.0</code>.</p>

  <p>There are also various special version conventions (such as all the
  revision components in <code>1.4-5+deb10u1~bpo9u1</code>) but they all
  appear to express relationships between native packages and/or their
  upstream and thus do not apply to our case.</p>

  <p>To recap, the <code>bpkg</code> version has the following form (see <a
  href="#package-version">Package Version</a> for details):</p>

  <pre>[+&lt;epoch>-]&lt;upstream>[-&lt;prerel>][+&lt;revision>]</pre>

  <p>Let's start with the case where neither distribution
  (<code>debian-version</code>) nor upstream version
  (<code>upstream-version</code>) is specified and we need to derive
  everything from the <code>bpkg</code> version (what follows is as much
  description as rationale).</p>

  <dl>
  <dt><code>&lt;epoch></code></dt>
  <dd>On one hand, if we keep our (as in, <code>bpkg</code>) epoch, it won't
  necessarily match Debian's native package epoch. But on the other it will
  allow our binary packages from different epochs to co-exist. Seeing that
  this can be easily overridden with a custom distribution version (see
  below), we keep it.

  <p>Note that while the Debian start/default epoch is 0, ours is 1 (we use
  the 0 epoch for stub packages). So we shift this value range.</p></dd>

  <dt><code>&lt;upstream>[-&lt;prerel>]</code></dt>
  <dd>Our upstream version maps naturally to Debian's. That is, our upstream
  version format/semantics is a subset of Debian's.

  <p>If this is a pre-release, then we could fail (that is, don't allow
  pre-releases) but then we won't be able to test on pre-release packages, for
  example, to make sure the name mapping is correct. Plus sometimes it's
  useful to publish pre-releases. We could ignore it, but then such packages
  will be indistinguishable from each other and the final release, which is
  not ideal. On the other hand, Debian has the mechanism (<code>~</code>)
  which is essentially meant for this, so we use it. We will use
  <code>&lt;prerel></code> as is since its format is the same as upstream and
  thus should map naturally.</p></dd>

  <dt><code>&lt;revision></code></dt>
  <dd>Similar to epoch, our revision won't necessarily match Debian's native
  package revision. But on the other hand it will allow us to establish a
  correspondence between source and binary packages. Plus, upgrades between
  binary package revisions will be handled naturally. Seeing that we allow
  overriding the revision with a custom distribution version (see below), we
  keep it.

  <p>Note also that both Debian and our revision start/default is 0. However,
  it is Debian's convention to start revision from 1. But it doesn't seem
  worth it for us to do any shifting here and so we will use our revision as
  is.</p>

  <p>Another related question is whether we should also include some metadata
  that identifies the distribution and its version that this package is for.
  The strongest precedent here is probably Ubuntu's PPA. While there doesn't
  appear to be a consistent approach, one can often see versions like
  these:</p>

  <pre>2.1.0-1~ppa0~ubuntu14.04.1,
1.4-5-1.2.1~ubuntu20.04.1~ppa1
22.12.2-0ubuntu1~ubuntu23.04~ppa1</pre>

  <p>Seeing that this is a non-sortable component (what in semver would be
  called "build metadata"), using <code>~</code> is probably not the worst
  choice.</p>

  <p>So we follow this lead and add the <code>~&lt;ID>&lt;VERSION_ID></code>
  <code>os-release(5)</code> component to revision. Note that this also means
  we will have to make the 0 revision explicit. For example:</p>

  <pre>1.2.3-1~debian10
1.2.3-0~ubuntu20.04</pre></dd>
  </dl>

  <p>The next case to consider is when we have the upstream version
  (<code>upstream-version</code> manifest value). After some rumination it
  feels correct to use it in place of the
  <code>&lt;epoch>-&lt;upstream></code> components in the above mapping
  (upstream version itself cannot have epoch). In other words, we will add the
  pre-release and revision components from the <code>bpkg</code> version. If
  this is not the desired semantics, then it can always be overridden with the
  distribution version (see below).</p>

  <p>Finally, we have the distribution version. The Debian
  <code>&lt;epoch></code> and <code>&lt;upstream></code> components are
  straightforward: they should be specified by the distribution version as
  required. This leaves pre-release and revision. It feels like in most cases
  we would want these copied over from the <code>bpkg</code> version
  automatically &#8211; it's too tedious and error-prone to maintain them
  manually. However, we want the user to have the full override ability. So
  instead, if empty revision is specified, as in <code>1.2.3-</code>, then we
  automatically add the <code>bpkg</code> revision. Similarly, if empty
  pre-release is specified, as in <code>1.2.3~</code>, then we add the
  <code>bpkg</code> pre-release. To add both automatically, we would specify
  <code>1.2.3~-</code> (other combinations are <code>1.2.3~b.1-</code> and
  <code>1.2.3~-1</code>).</p>

  <p>Note also that per the Debian version specification, if upstream contains
  <code>:</code> and/or <code>-</code>, then epoch and/or revision must be
  specified explicitly, respectively. Note that the <code>bpkg</code> upstream
  version may not contain either.</p>

  <h2 id="bindist-mapping-fedora">7.2 Fedora Package Mapping</h2>

  <p>This section describes the distribution package mapping for Fedora and
  alike (Red Hat Enterprise Linux, Centos, etc).</p>

  <h3 id="bindist-mapping-fedora-consume">7.2.1 Fedora Package Mapping for
  Consumption</h3>

  <p>A library in Fedora is normally split up into several packages: the
  shared library package (e.g., <code>libfoo</code>), the development files
  package (e.g., <code>libfoo-devel</code>), the static library package (e.g.,
  <code>libfoo-static</code>; may also be placed into the <code>-devel</code>
  package), the documentation files package (e.g., <code>libfoo-doc</code>),
  the debug symbols and source files packages (e.g.,
  <code>libfoo-debuginfo</code> and <code>libfoo-debugsource</code>), and the
  common or architecture-independent files (e.g., <code>libfoo-common</code>).
   All the packages except <code>-devel</code> are optional and there is quite
  a bit of variability. In particular, the <code>lib</code> prefix in
  <code>libfoo</code> is not a requirement (unlike in Debian) and is normally
  present only if upstream name has it (see some examples below).</p>

  <p>For application packages there is normally no <code>-devel</code>
  packages but <code>-debug*</code>, <code>-doc</code>, and
  <code>-common</code> are plausible.</p>

  <p>For mixed packages which include both applications and libraries, the
  shared library package normally has the <code>-libs</code> suffix (e.g.,
  <code>foo-libs</code>).</p>

  <p>A package name may also include an upstream version based suffix if
  multiple versions of the package can be installed simultaneously (e.g.,
  <code>libfoo1.1</code> <code>libfoo1.1-devel</code>, <code>libfoo2</code>
  <code>libfoo2-devel</code>).</p>

  <p>Terminology-wise, the term "base package" (sometime also "main package")
  normally refers to either the application or shared library package (as
  decided by the package maintainer in the spec file) with the suffixed
  packages (<code>-devel</code>, <code>-doc</code>, etc) called
  "subpackages".</p>

  <p>Here are a few examples:</p>

  <pre>libpq libpq-devel

zlib zlib-devel zlib-static

catch-devel

eigen3-devel eigen3-doc

xerces-c xerces-c-devel xerces-c-doc

libsigc++20 libsigc++20-devel libsigc++20-doc
libsigc++30 libsigc++30-devel libsigc++30-doc

icu libicu libicu-devel libicu-doc

openssl openssl-libs openssl-devel openssl-static
openssl1.1 openssl1.1-devel

curl libcurl libcurl-devel

sqlite sqlite-libs sqlite-devel sqlite-doc

community-mysql community-mysql-libs community-mysql-devel
community-mysql-common community-mysql-server

ncurses ncurses-libs ncurses-c++-libs ncurses-devel ncurses-static

keyutils keyutils-libs keyutils-libs-devel</pre>

  <p>Note that while we support arbitrary <code>-debug*</code> sub-package
  names for consumption, we only generate
  <code>&lt;main-package>-debug*</code>.</p>

  <p>Based on that, our approach when trying to automatically map a
  <code>bpkg</code> library package name to Fedora package names is to go for
  the <code>-devel</code> package first and figure out the shared library
  package from that based on the fact that the <code>-devel</code> package
  should have the <code>==</code> dependency on the shared library package
  with the same version and its name should normally start with the
  <code>-devel</code> package's stem and potentially end with the
  <code>-libs</code> suffix. If failed to find the <code>-devel</code>
  package, we re-try but now using the <code>bpkg</code> project name instead
  of the package name (see, for example, <code>openssl</code>,
  <code>sqlite</code>).</p>

  <p>The format of the <code>fedora-name</code> (or alike) manifest value
  value is a comma-separated list of one or more package groups:</p>

  <pre>&lt;package-group> [, &lt;package-group>...]</pre>

  <p>Where each <code>&lt;package-group></code> is the space-separated list of
  one or more package names:</p>

  <pre>&lt;package-name> [ &lt;package-name>...]</pre>

  <p>All the packages in the group should belong to the same "logical
  package", such as <code>-devel</code>, <code>-doc</code>,
  <code>-common</code> packages. They normally have the same version.</p>

  <p>The first group is called the main group and the first package in the
  group is called the main package. Note that all the groups are consumed
  (installed) but only the main group is produced (packaged).</p>

  <p>(Note that above we use the term "logical package" instead of "base
  package" since the main package may not be the base package, for example
  being the <code>-libs</code> subpackage.)</p>

  <p>We allow/recommend specifying the <code>-devel</code> package instead of
  the main package for libraries (see <a
  href="#manifest-package-type-language"><code>type</code></a> for details),
  seeing that we are capable of detecting the main package automatically (see
  above). If the library name happens to end with <code>-devel</code> (which
  poses an ambiguity), then the <code>-devel</code> package should be
  specified explicitly as the second package to disambiguate this
  situation.</p>

  <p>The Fedora package version has the
  <code>[&lt;epoch>:]&lt;version>-&lt;release></code> form (see Fedora Package
  Versioning Guidelines for details). If no explicit mapping to the
  <code>bpkg</code> version is specified with the
  <code>fedora-to-downstream-version</code> (or alike) manifest values or none
  match, then we fallback to using the <code>&lt;version></code> part as the
  <code>bpkg</code> version. If explicit mapping is specified, then we match
  it against the <code>[&lt;epoch>:]&lt;version></code> parts ignoring
  <code>&lt;release></code>.</p>

  <h3 id="bindist-mapping-fedora-produce">7.2.2 Fedora Package Mapping for
  Production</h3>

  <p>The same <code>fedora-name</code> (or alike) manifest values as used for
  consumption are also used to derive the package names for production except
  here we have the option to specify alternative non-native package names
  using the special <code>fedora_0-name</code> (or alike) value. If only the
  <code>-devel</code> package is specified, then the main package name is
  derived from that by removing the <code>-devel</code> suffix. Note that
  regardless of whether the main package name is specified or not, the <a
  href="bpkg-pkg-bindist.xhtml"><code><b>bpkg-pkg-bindist(1)</b></code></a>
  command may omit generating the main package for a binless library.</p>

  <p>The generated binary package version can be specified with the
  <code>fedora-version</code> (or alike) manifest value. If it's not
  specified, then the <code>upstream-version</code> is used if specified.
  Otherwise, the <code>bpkg</code> version is translated to the Fedora version
  as described next.</p>

  <p>To recap, a Fedora package version has the following form:</p>

  <pre>[&lt;epoch>:]&lt;version>-&lt;release></pre>

  <p>Where &lt;release> has the following form:</p>

  <pre>&lt;release-number>[.&lt;distribution-tag>]</pre>

  <p>For details on the ordering semantics, see the Fedora Versioning
  Guidelines. While overall unsurprising, the only notable exceptions are
  <code>~</code>, which sorts before anything else and is commonly used for
  upstream pre-releases, and <code>^</code>, which sorts after anything else
  and is supposedly used for upstream post-release snapshots. For example,
  <code>0.1.0~alpha.1-1.fc35</code> sorts earlier than
  <code>0.1.0-1.fc35</code>.</p>

  <p>To recap, the bpkg version has the following form (see <a
  href="#package-version">Package Version</a> for details):</p>

  <pre>[+&lt;epoch>-]&lt;upstream>[-&lt;prerel>][+&lt;revision>]</pre>

  <p>Let's start with the case where neither distribution
  (<code>fedora-version</code>) nor upstream version
  (<code>upstream-version</code>) is specified and we need to derive
  everything from the <code>bpkg</code> version (what follows is as much
  description as rationale).</p>

  <dl>
  <dt><code>&lt;epoch></code></dt>
  <dd>On one hand, if we keep our (as in, <code>bpkg</code>) epoch, it won't
  necessarily match Fedora's native package epoch. But on the other it will
  allow our binary packages from different epochs to co-exist. Seeing that
  this can be easily overridden with a custom distribution version (see
  below), we keep it.

  <p>Note that while the Fedora start/default epoch is 0, ours is 1 (we use
  the 0 epoch for stub packages). So we shift this value range.</p></dd>

  <dt><code>&lt;upstream>[-&lt;prerel>]</code></dt>
  <dd>Our upstream version maps naturally to Fedora's
  <code>&lt;version></code>. That is, our upstream version format/semantics is
  a subset of Fedora's <code>&lt;version></code>.

  <p>If this is a pre-release, then we could fail (that is, don't allow
  pre-releases) but then we won't be able to test on pre-release packages, for
  example, to make sure the name mapping is correct. Plus sometimes it's
  useful to publish pre-releases. We could ignore it, but then such packages
  will be indistinguishable from each other and the final release, which is
  not ideal. On the other hand, Fedora has the mechanism (<code>~</code>)
  which is essentially meant for this, so we use it. We will use
  <code>&lt;prerel></code> as is since its format is the same as
  <code>&lt;upstream></code> and thus should map naturally.</p></dd>

  <dt><code>&lt;revision></code></dt>
  <dd>Similar to epoch, our revision won't necessarily match Fedora's native
  package release number. But on the other hand it will allow us to establish
  a correspondence between source and binary packages. Plus, upgrades between
  binary package releases will be handled naturally. Also note that the
  revision is mandatory in Fedora. Seeing that we allow overriding the
  releases with a custom distribution version (see below), we use it.

  <p>Note that the Fedora start release number is 1 and our revision is 0. So
  we shift this value range.</p>

  <p>Also we automatically add the trailing distribution tag
  (<code>.fc35</code>, <code>.el8</code>, etc) to the Fedora release. The tag
  is deduced automatically unless overridden on the command line (see <a
  href="bpkg-pkg-bindist.xhtml"><code><b>bpkg-pkg-bindist(1)</b></code></a>
  command for details).</p></dd>
  </dl>

  <p>The next case to consider is when we have the upstream version
  (<code>upstream-version</code> manifest value). After some rumination it
  feels correct to use it in place of the
  <code>&lt;epoch>-&lt;upstream></code> components in the above mapping
  (upstream version itself cannot have epoch). In other words, we will add the
  pre-release and revision components from the <code>bpkg</code> version. If
  this is not the desired semantics, then it can always be overridden with the
  distribution version (see below).</p>

  <p>Finally, we have the distribution version. The Fedora
  <code>&lt;epoch></code> and <code>&lt;version></code> components are
  straightforward: they should be specified by the distribution version as
  required. This leaves pre-release and release. It feels like in most cases
  we would want these copied over from the <code>bpkg</code> version
  automatically &#8211; it's too tedious and error-prone to maintain them
  manually. However, we want the user to have the full override ability. So
  instead, if empty release is specified, as in <code>1.2.3-</code>, then we
  automatically add the <code>bpkg</code> revision. Similarly, if empty
  pre-release is specified, as in <code>1.2.3~</code>, then we add the
  <code>bpkg</code> pre-release. To add both automatically, we would specify
  <code>1.2.3~-</code> (other combinations are <code>1.2.3~b.1-</code> and
  <code>1.2.3~-1</code>). If specified, the release must not contain the
  distribution tag, since it is deduced automatically unless overridden on the
  command line (see <a
  href="bpkg-pkg-bindist.xhtml"><code><b>bpkg-pkg-bindist(1)</b></code></a>
  command for details). Also, since the release component is mandatory in
  Fedora, if it is omitted together with the separating dash we will add the
  release 1 automatically.</p>

  <p>Note also that per the RPM spec file format documentation neither version
  nor release components may contain <code>:</code> or <code>-</code>. Note
  that the <code>bpkg</code> upstream version may not contain either.</p>

</div>

</body>
</html>
